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 available with managed services.

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. The panel also sends the pair as the X-Org-Slug and X-Workspace-Slug headers on every call, and the engine validates the workspace header on every route - a mistyped workspace is refused rather than quietly answering from another one.

GET /api/me returns the caller’s tenancy - every organization they hold, each with the workspaces they can actually reach inside it (not every workspace the organization owns), plus the workspace they last worked in - and the panel builds and validates its tenant URLs from it. It requires only that you are signed in - no RBAC permission at all. That is deliberate: the caller who most needs this route is the one with no binding yet, a fresh invitee or an account a platform admin just created, and gating it on a permission answered them 403 instead of an empty tenancy. A caller who belongs to nothing gets a 200 with no organizations, which is what lets the panel say so instead of looking broken.

PUT /api/workspaces/active records the preference by workspace slug (permission org:read) so a returning operator resumes where they left off. The preference is honoured only while it is still reachable and still in the organization it was recorded in - otherwise the panel falls back to that organization’s default workspace, then to the first reachable one. Two workspaces in different organizations can share a slug, so a bare preference would otherwise pick the wrong one.

Switching workspace is a navigation, not a stored mode: it keeps the page you are on, and a detail page truncates to its list. There is no active-workspace cookie - a second notion of “the current workspace” is how a URL and a request come to name different ones.

Which workspaces appear depends on the deployment:

The test is the role level, not the role key: a custom role at level 30 or above sees every workspace too. Comparing keys instead would have silently excluded every custom role from a rule that is about seniority.

An operator with no binding and no membership sees none.

Managing workspaces

Managed services. The Workspaces screen and its API require the workspace-scoped-RBAC feature.

The Workspaces screen lives in Settings → Organization, at /organizations/{org}/settings/organization/workspaces. It needs workspace:write on a deployment where the feature is licensed.

That permission exists because this page edits the organization’s structure, not its people. It used to be gated on org.member:manage - so creating a workspace was governed by a permission literally named “manage members”, and “may create workspaces but not administer people” could not be expressed by a custom role at all. The three concerns are now separable:

All three are held by Admin and above, so nothing changed for the built-in roles - the split is what makes a custom role able to hold one without the others.

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

Managed services.

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 Members and roles, which needs workspace.member:manage. Each member’s row expands to one role select per workspace of the organization, so a person’s placement is changed in one place without switching workspace. Both mutations land in the authorization audit.

For the full resolution order, including the platform-admin bypass, see Roles and permissions.

What a workspace may draw on

A workspace does not automatically get everything its organization holds. A skill, a plugin or an AI provider reaches an agent only when both boundaries agree: the organization must hold it - its own skill, a granted platform skill, an installed or granted plugin, an admitted provider - and the agent’s workspace must have it assigned. Either one missing and the agent never sees it.

The screens that edit the workspace half live in the workspace tier of Settings, and all need workspace.assignment:manage (Admin and above):

Skills, Plugins and Providers each list only what the organization holds, with one switch per row. The Skills page lists the organization’s catalogue; the Plugins page lists the plugins the organization has installed or been granted; the Providers page lists the providers the organization is admitted to. A plugin or provider the organization does not hold is absent, not shown as disabled: what other tenants of the installation run is not disclosed. A plugin the engine cannot run is flagged separately; enabling it there has no effect either way.

Three consequences worth knowing before you rely on it

• A new workspace starts empty. There is no inheritance and no snapshot at creation, so an agent moved into a fresh workspace has no skills and no plugin tools until someone assigns them. This reads like a bug the first time it happens; it is the fail-closed direction, chosen deliberately.
• A new grant at organization level reaches no workspace. Granting a platform skill or a plugin to the organization, or installing a plugin there, makes it assignable; it does not assign it. The workspace pass is a second, manual step.
• Revoking assigns nothing away permanently. Revoking touches only the workspace allow-list - each agent’s own skill rows survive, so re-assigning restores every agent’s configuration exactly. This is the same rule that governs an organization-level revoke.

The Providers page is the same shape. With managed services, the Available connections page beside it lists the provider connections the workspace’s agents can choose: the workspace’s own and those the organization lends it. A workspace’s own connection, created there with New workspace connection, is usable by that workspace’s agents alone; an organization connection is lent with From the organization… and withdrawn with Remove from this workspace. Lending is what lets an agent in the workspace bind that credential to a role by name, and withdrawing it is the everyday revoke - agents bound to that connection stop at their next call rather than quietly falling back onto another key. An organization set to accept only its own connections refuses workspace connections, at creation and at every call. A workspace’s shared library is embedded with the organization’s library connection only where that connection is lent to the workspace. Switching a single model off here is a veto that the organization cannot undo, and the reverse holds too; see AI Gateway. The assignment binds every call an agent makes to a provider: chat, and also the embeddings behind memories, knowledge documents and search queries, and speech-to-text. A connection or key on a provider this workspace has not assigned is refused for all of them.

The one automatic assignment is an agent creating a skill at runtime: createSkill assigns the new skill to that agent’s own workspace, because a skill an agent just wrote and cannot then use would be committed and dead.

Where an operator meets the allow-list

The allow-list filters reads as well as writes, so a gap shows up as an explanation rather than a silently shorter list:

• An agent’s Tools and Skills tabs report how many of the things configured on that agent the workspace does not carry - a count, never the names, because the names are organization-tier information and these tabs are reachable with workspace-tier permissions.
• The agent’s Status section reports the same gaps as checks, and says where to fix them.

On upgrade

The migration that introduced the allow-list backfills every workspace that existed at the time with everything its organization held, so an upgrade changes nothing for a running deployment. The empty-by-default rule applies only to workspaces created afterwards.

Providers were introduced the same way and with one deliberate difference: a new workspace admits every provider its organization holds, and a new organization is admitted every provider the catalogue knows. An empty plugin allow-list is an agent with fewer tools; an empty provider allow-list is an agent that cannot answer at all, so starting empty would mean every organization created after the feature shipped was born dead.

The list is read at creation and not followed afterwards: a provider the platform gives the organization later is a decision its admins take again, workspace by workspace. That is the tier split the feature exists to keep.

See also

• Organizations - the tenant a workspace belongs to.
• Skills - the catalogue the workspace allow-list draws from.
• Tools - the plugin half of the same rule.
• Members and roles - assigning organization and workspace roles.
• Agents (General) - the objects a workspace contains.