Workspaces
An end-user owns their own rows. A workspace lets a group of end-users share rows: a farm, a company, an accounting office. A workspace lives inside one Identity app. It is not an Orkestia organization, which is a paying customer.
What you can do
| Action | Workflow |
|---|---|
| Create a workspace (name, unique slug, optional kind) | identity.app-organization.create |
| Add an existing end-user with a role | identity.app-organization.add-member |
| Invite someone by email, pending until accepted | identity.app-organization.invite |
| Change a member's role | identity.app-organization.assign-role |
| List workspaces and members | identity.app-organization.query |
| Move the signed-in user to another workspace | identity.end-user.organization.switch |
A role is an access group (group_slug) you have defined for the app. It maps to capabilities such as {namespace}:{verb}.
Let people switch workspaces in your app
Your app's users can only start workflows you expose to the app, so they can't call identity.end-user.organization.switch themselves. Publish a composition with one step that wraps it, and expose that composition:
- Give the composition an input with any name except
app_organization_uuid, for exampleworkspace_uuid, and map it to the step'sapp_organization_uuid. A user's input may not useapp_organization_uuidas a key: the active workspace comes from the server, so the platform refuses such a start withPRINCIPAL_OVERRIDE_REJECTED. - The switch checks that the user is a member of the workspace they asked for. Your app doesn't need to check it again.
From then on, the user's runs and workspace rows use the new workspace.
If your app has turned on end-user authoring, it already has this composition: composer-workspace-switch-<app12>, with the input workspace_uuid.
Sessions bound to a workspace
A session token can be bound to one workspace: send app_organization_uuid when you exchange the code or refresh the token at POST /api/auth/end-user/token. With a bound token, starting a workflow while the user's active workspace is a different one fails with 403 and code: "WORKSPACE_MISMATCH". The reason field says why:
reason | Meaning |
|---|---|
active_workspace_differs | The user switched to another workspace after this token was issued. |
no_active_workspace | The user has no active workspace now, for example because they were removed from it. |
After a switch, refresh the token with the new app_organization_uuid, switch back to the token's workspace, or use an unbound token. An unbound token always follows the active workspace.
Automations in a workspace
People in a workspace can build, check, publish, run and schedule their own compositions there. Each composition belongs to the workspace, and the person's role there decides what they may do. By default, members draft and run; admins and owners also publish. See End-user authoring.
People without an email
An end user who only uses WhatsApp has a verified phone number and no email (see People who only use WhatsApp). Add them with identity.app-organization.add-member and their end_user_uuid. Invites go out by email, so identity.app-organization.invite and the in-app identity.end-user.organization.invite-member cannot reach them.
Data in a workspace
Declare a table with organization ownership and its rows belong to the user's active workspace. See Ownership. The active workspace comes from the server, not from the request, so a caller cannot choose another one.
Pricing and limits
What is billed for apps you build, how end-user seats work, where to see your hosting usage, and the quotas that apply to sites, processes and volumes.
End-user authoring
Let the end users of your app build, check, publish, run and schedule their own small workflows (compositions) inside their workspace.