Team and roles
Deployment accounts and sign-in, the five built-in space roles (Viewer, Approver, Editor, Manager, Administrator), setting up a new deployment's first admin, recovering admin access, and the last-administrator rule.
Access has two layers. A person first needs an account on the deployment, which is how they sign in to the admin. Then, in each space they work in, they have a space role, as does every API key your integrations use. Every space starts with five built-in roles. They are ordered, so each one can do everything the roles before it can:
| Role | Can |
|---|---|
| Viewer | Read drafts and published content, workflows and approvals; search |
| Approver | Also approve and reject workflow approvals |
| Editor | Also write and publish content, start and cancel workflow runs, and deliver workflow events |
| Manager | Also change how content is structured: content types, workflows, taxonomy, functions and AI actions |
| Administrator | Also manage the team, API keys, roles, webhooks, environments, plugins and the audit log |
Each role is a set of permission scopes. The built-in ones are ordinary roles: you can edit them (their name, scopes and per-content-type grants), and Clone one under Settings → Roles to start a custom role from it. A built-in role can’t be deleted.
Approver’s one extra scope is workflow:approve, which every role from Approver up holds. An
approval step lets anyone holding it decide unless the step asks for something else
(content:publish, say, for a legal sign-off).
Accounts and sign-in
Section titled “Accounts and sign-in”Admins manage the deployment’s accounts at People and sign-in (/team). An account is a
Member, who signs in and works within the space roles they’re given, or an Admin, who also
manages accounts, single sign-on, SCIM provisioning and the audit log, and administers every space.
- People. Add someone with their email, a name and an account role. They get a temporary password, shown once, to send them privately with the sign-in page; they choose their own the first time they sign in.
- Sign-in methods. A password, a passkey, or your organization’s single sign-on (OpenID Connect) when the deployment has an identity provider configured. Two-factor sign-in with an authenticator app can be required.
- SCIM provisioning. Your identity provider can add, update and turn off people through the
SCIM endpoint (
/scim/v2) with a token made on this page. Turning someone off signs them out everywhere and disconnects their apps and the API tokens they made. - Ending access. Disabling someone, resetting their password, or resetting their two-factor sign-in does the same: their sessions end, the MCP connections they approved and the personal access tokens they made stop working in every space, and a password or two-factor reset also removes their passkeys. Your space’s own API keys are not a person’s and keep working.
Space access
Section titled “Space access”Administrators of a space manage who works in it at Settings → Access → Space access:
- People in this space. Add someone by email with a space role; their email links their account to the space. Change a role from the list, which asks you to confirm in place. Turn off refuses their access to the space until you turn it back on; Remove takes them off it. A deployment Admin who isn’t on a space’s team still administers it.
- API keys. Every long-lived key with the role it acts with. Change a key’s role the same way; mint and revoke keys under Settings → API keys.
Over the API, the same page is GET /spaces/{space}/team, with POST …/members,
PATCH …/members/{id}, PUT …/api-keys/{id}/role and PUT …/access-settings; a role can be named
by id or by preset (viewer, approver, editor, manager, admin). The MCP server has
role_presets_list, team_list and role_preset_assign.
The last administrator
Section titled “The last administrator”A space that has an administrator always keeps one. The last one can’t be demoted, turned off,
removed or revoked, and the Administrator role can’t lose space:admin while it is all that makes
anyone an administrator: the page says so where you’d make the change, and the API answers 409
last_admin. Make someone else an administrator first.
Setting up a new deployment
Section titled “Setting up a new deployment”A new deployment has no accounts, and until it does, every admin page except /setup sends a
browser there. Whoever runs the deployment sends you
the link to /setup and a one-time setup code. Enter the code, your email, a name and a
password: that creates your Admin account and signs you in on People and sign-in, where you add
everyone else.
The code works once. A wrong code is refused, throttled per address, and recorded in the audit log.
Recovering admin access
Section titled “Recovering admin access”If no admin can sign in, ask whoever runs the deployment for a new setup code (they run
scripts/setup-code.sh). It opens /setup once more, now titled Recover admin access, and
whoever uses it gets a new Admin account, recorded in the audit log as team.recovery_admin.