Access control
Fixed roles, scoped permissions and the separation between platform and tenant administration.
Tokamak authorizes actions using permissions held by a principal at the resource's scope. Auth owns the RBAC store; gateway and core consume verified authority. Browser controls supplement server-side checks.
The model in one sentence
An assignment grants a fixed role to a principal at a scope; the role supplies permissions, and each operation checks the permission and target it requires.
Scopes
| Scope | Target |
|---|---|
platform | The deployment and cross-tenant operations. |
org | One organization. |
team | One team within one organization. Teams may be nested (People → Structure), but a team role is held on that one team only; it does not extend to its sub-teams or its parent. |
Platform standing never substitutes for an organization permission. Organization-to-team authority follows an explicit mapping; it is not unrestricted inheritance across every resource. Removed project-management scope names do not create supported product features.
Roles
| Role | Platform | Organization | Team |
|---|---|---|---|
| Owner | Platform administration with recovery protections | Organization authority including protected owner operations | Team authority including ownership transfer |
| Admin | Platform administration | Organization administration except owner-only lifecycle/transfer | Team administration except ownership transfer |
| Member | Baseline permitted platform discovery | org.members.view plus personal surfaces | team.view, team.members.view |
| Billing Admin | Not available | org.billing.view, org.billing.manage, org.usage_limits.manage | Not available |
The fixed role model rejects custom and derived role creation with 409 role_model_frozen. System roles are protected. Legacy role-definition routes and storage are not evidence that custom-role creation is enabled. Manager is retired.
Permission catalog
Use the server's permission snapshot and catalog when building integrations rather than inferring authority from a role label or caching an old count.
Platform scope
Platform permissions cover users, organizations, providers/models, deployment settings and other cross-tenant operations. A platform operator who has no authority at an organization cannot manage its members or money merely by being a platform operator.
Organization scope
Directory reads use org.members.view. Membership and setting mutations retain organization administration requirements. Billing reads and writes use org.billing.view and org.billing.manage; budgets and organization usage use org.usage_limits.manage. An organization's own provider keys (bring your own key) use org.providers.manage, and their internal prices use org.models.manage; owners and admins hold both. Neither is available to an inference API key. The organization's agents (service accounts) and their keys use org.agents.manage, held by owners and admins, and a team's own agents also team.admin at that team, held by the team's owners and admins; an agent's own keys are inference keys and are refused on every account and management route.
Team scope
Team roles include view, member-view, usage-view, administration and ownership-transfer permissions as appropriate. Customer directory GET routes use the organization member-read gate; specific team operations and attribution additionally validate the target. A visible team does not automatically mean its usage is visible or its roster editable.
Bootstrapping admin access
SYSTEM_ADMIN_EMAIL seeds configured platform authority at startup. It does not grant tenant-internal permissions. Configure production authentication and operator access explicitly; preview login is a local development facility, not a production access policy.
Owner floor
Removing or demoting the final eligible owner is refused. Assignment expiry and membership synchronization must preserve the same rule. Use the supported atomic transfer workflow rather than separate demotion and promotion writes. Platform recovery has its own eligible-administrator rule; do not assume tenant ownership checks and platform recovery are identical.
Resolution and caching
Permissions are scoped and versioned. Organization or identity changes invalidate scoped frontend state. Membership changes propagate through the existing core-to-auth outbox, so a core mutation and auth's mirrored result need not become visible simultaneously.
Personal default-team keys verify live mirrored membership in the credential query. There is no permission cache that deliberately extends removed membership, and a missing attribution is a refusal rather than a switch to unassigned traffic.
API surface
GET /v1/me/permissions exposes the caller's snapshot. The RBAC administration family is /v1/admin/rbac/*: role/catalog reads, assignments, scope grants and audit records have target-specific authorization. Reaching the RBAC router does not authorize every scope it can name.
POST /v1/admin/rbac/roles remains a compatibility endpoint that refuses custom-role creation. Do not build a new role editor around it. Assignment writes must preserve fixed roles, owner floors, audit and RBAC version bumps.
Common operations
Use People for tenant membership and the platform console for platform assignments. Before a grant or revocation, check the principal, scope, role and intended duration. Use returned identifiers; never copy hard-coded role IDs between deployments.
The customer organization Access control page is a placeholder. It is not an alternative route to custom-role creation.