Workspaces, members and roles
A workspace defines membership, permissions, billing, and the data boundary for work.
A workspace is the boundary for the people, settings, credits, and work your team shares. Use it when you need to add a collaborator, understand who can work in the organization, or confirm which workspace holds a setting.
Context belongs to the knowledge store, while tags, comments, and saved views stay with the workspace. API keys are also scoped to one workspace, as described in API keys and scopes.
What the workspace contains
The workspace pack owns collaborators, membership, organization settings, credit information, agency, tags, comments, and saved views. This boundary prevents a workspace setting or credential from silently applying to another workspace.
| Area | What belongs here |
|---|---|
| Members | Collaborators and their membership in this workspace. |
| Organization settings | The settings that apply to this workspace. |
| Credits and billing | The workspace credit balance, allowance, spending ledger, and billing. |
| Agency and views | Agency work, tags, comments, and saved views that belong to the workspace. |
Manage members and roles
Open /dashboard/settings and choose the members area to review collaborators and their roles. Check the active workspace before you make a change, because membership belongs to that workspace rather than to a global team list.
Check before changing access
Start by confirming the collaborator, the active workspace, and the role you intend to change. Then return to Settings and verify that the member list shows the expected result. A workspace may hold billing, credits, and integrations alongside membership, so changing access has consequences beyond a single screen.
Operate within the workspace boundary
Workspace controls apply to one organization at a time. The notes below describe the boundaries and failure results that matter when a team reads settings, changes membership, or transfers ownership.
A workspace is not only a label in the sidebar. It is the boundary that carries collaborators, settings, credits, billing, tags, comments, saved views, portable snapshots, notification delivery, callback URLs, and event webhooks.
Open Settings with the intended workspace active. The application has separate Members, Workspace, Roles, and workspace-notifications settings areas, so a change in one area should not be assumed to have changed another.
Read the current workspace settings immediately before changing a workspace setting. The returned updated_at value is the optimistic-concurrency value required by the settings update operation.
A settings update changes only fields sent in the request. Omitted fields remain untouched, and a workspace settings update cannot change ownership, membership, plan, or seats.
If the settings row changed after it was read, the write is refused with state_version_conflict and nothing changes. Read the current row again, compare the intended change with the current state, then resubmit only the fields still intended.
Member roles are owner, admin, member, and client. An admin can update workspace settings, invite and cancel invitations, and view billing; a member or client has a different workspace role and must not be described as an owner.
Changing a member role applies to an existing non-support membership in this workspace. The operation cannot make a member an owner and cannot change the publishing role.
A role change refuses invalid_member_role_change when the target is the caller, the workspace owner, or an unsupported role. It refuses member_not_found when no matching non-support membership exists.
Removing a member deletes the membership row, which removes that person’s workspace access immediately. It does not delete the person’s user account, their authored work, or a subscription seat.
A removal refuses invalid_member_removal when the target is the caller or the workspace owner. It refuses member_not_found when there is no matching non-support membership, and adding the person back requires a new invitation and acceptance.
Ownership transfer is separate from role editing. It makes the selected member the owner, demotes the previous owner to member, and repoints the workspace owner in one transaction.
Ownership transfer is not a reversible workspace operation. It refuses invalid_new_owner when the target is the current owner, is not a non-support workspace member, or is absent, and it refuses owner_authority_changed if the caller stopped being owner during the operation.
Workspace keys, membership, and spending policy are scoped to the workspace. A machine key cannot switch workspaces, so an automation should use a key belonging to the workspace where it is meant to operate.
Context is deliberately outside the workspace pack’s durable-state boundary. Store a product decision or buyer finding in Context, then use workspace tags, comments, or a saved view to organize the operational work around it.
Verify the change in the app
Agency work is also owned by the workspace pack, while external provider credentials belong to Integrations. This distinction keeps a workspace management task from being confused with a provider connection change.
Architect can inspect workspace state using the same canonical controls available through other doors. It should search for the active capability and fetch its schema before a run, then report the returned workspace or membership result.
A read-only workspace inspection is free when its capability cost policy says zero credits. A mutation still requires an explicit mode, because the server never defaults a mutating call to live.
Check the visible member list or Settings result after a change. The result should identify the affected member or workspace state, and the app should show the active workspace that received the change.
Do not use a workspace settings write to repair a credit, billing, ownership, or membership issue that belongs to a distinct capability. Read the specific state first, then choose the operation that owns that state.
When you are unsure which workspace contains the work, stop before a mutation. The correct repair is to inspect the active workspace and membership, not to duplicate the setting in several workspaces.
Use the workspace result and the Settings screen together. A response object is the record of the capability result, while the app confirms that the intended workspace now displays the expected collaborators or settings.
| Requested change | Check before moving on |
|---|---|
| Settings update | Read updated_at, submit intended fields, and confirm the resulting workspace settings. |
| Member role | Confirm target membership, selected role, and the returned member role. |
| Member removal | Confirm the target is not the caller or owner, then confirm the member is absent. |
| Ownership transfer | Confirm the new owner is an eligible member and inspect the returned owner state. |
When it goes wrong
If a role change or removal is refused, read the current member list and confirm the target is an eligible non-support member in the active workspace. For a stale settings write, read settings again and use the fresh updated_at value. For an ownership-transfer refusal, inspect membership and caller authority before trying again.
If the work belongs in Context, a provider connection, or billing rather than membership or settings, use the page and capability that owns that subject. Do not solve a boundary error by broadening a workspace member’s role without checking the actual need.