Workspaces
A workspace subdivides an organization. Every agent lives in exactly one, and the workspace switcher at the top of the admin panel decides which agents an operator is currently looking at.
Workspaces exist as a structural container on every deployment. Using them to scope permissions is an enterprise feature.
The workspace switcher
The active workspace is part of the URL: admin-panel routes are tenant-scoped, so the organization and the workspace being acted in are carried by the path rather than by hidden state.
GET /api/me returns the caller’s tenancy — the organization, the workspaces they can actually reach (not every workspace the organization holds), and the workspace they last worked in — and the panel builds and validates its tenant URLs from it. It requires org:read, which every system role holds, Viewer included. A session carrying no organization gets a 403, which the panel treats exactly like “no tenancy”: either way the remedy is to sign in again.
PUT /api/workspaces/active records the preference by workspace slug (permission agent:read) so a returning operator resumes where they left off. With no preference to honour, the panel falls back to the organization’s default workspace, then to the first reachable one.
Which workspaces appear depends on the deployment:
| Who sees every workspace in the organization | Who sees a subset | |
|---|---|---|
| Without workspace-scoped RBAC | any organization member (and platform superadmins) | — |
| With workspace-scoped RBAC | platform superadmins, Owners, Admins | Members and Viewers see only the workspaces they hold a workspace binding for |
An operator with no binding and no membership sees none.
Managing workspaces
Enterprise feature. The Workspaces screen and its API require the workspace-scoped-RBAC feature.
The Workspaces screen (/workspaces) is visible to an operator with org.member:manage on a deployment where the feature is enabled — workspace structure is treated as a membership-administration concern, so it is Admin-and-above rather than Owner-only.
Create a workspace with a slug and a name; both are editable afterwards. Slugs are URL path segments: lowercase alphanumerics separated by single dashes, and unique within the organization — a collision is refused rather than silently suffixed.
Two deletions are refused rather than cascaded: the organization’s default workspace can never be deleted, and a workspace that still owns agents returns a conflict — move or delete its agents first.
Every route also rejects a caller from a different organization, even one holding org.member:manage in their own.
Workspace-scoped bindings
Enterprise feature.
A user can hold a role on a workspace in addition to their organization role, and the workspace binding wins: for agents in that workspace it grants what the org role lacks and revokes what the org role grants. Most-specific-wins, in both directions.
That is what makes the common case expressible: an org-wide Admin who should only be a Viewer inside finance gets a Viewer binding on finance — not a subtraction from their org role.
Assign and remove workspace roles from the Members screen, which reads every binding in the organization to show each member’s per-workspace roles. Both mutations land in the authorization audit.
For the full resolution order, including the platform-superadmin bypass, see Roles and permissions.
See also
- Organizations — the tenant a workspace belongs to.
- Members — assigning organization and workspace roles.
- Agents (General) — the objects a workspace contains.