A program that manages rolter through the control-plane API, such as a CI job that rotates a project key, a GitOps pipeline that applies routes or a script that creates a project per customer, used to choose between two credentials: the admin token, which is superadmin over the whole deployment and shared by everything that holds it, or a person’s session, which belongs to a browser and expires. An API token is a third one: a named service account that holds one role at one organization, team or project.
The control plane resolves the token to that role, so every permission check works exactly as it does for a person holding it. A token with the member role on one project can do what a project member can do there and nothing else.
What a token can and cannot do#
- It holds one built-in role (
admin,member,viewer) or one custom role of the organization, at the scope it was minted for. It reaches that scope and everything below it, never a sibling or the level above. - It never reaches deployment-wide settings (feature flags, the security settings, cluster nodes, alerting, the configuration export) and never holds a deployment role. Those stay with the admin token, superadmins and the deployment roles.
- It cannot manage tokens: minting, listing, rotating and revoking answer
403for a token, so a leaked one cannot mint a successor that outlives its own revocation. - It reads request logs and analytics for the scope it holds, by the same rules as a person with that role: the rows of its project, team or org, and no others. The same read covers what shares that guard: the CSV export of the request log, the savings report, provider health, the log sampling rate and the MCP tool-call log. The captured request and response bodies are withheld unless the token’s role reaches the project’s
request_payloadfloor: amembertoken or better reads them, and aviewertoken reads them only on a project whose admin lowered the floor toviewer(payload_min_role). It is not a session: the dashboard’s account endpoints answer401. - It never grants access: adding, changing or removing a membership, sending or revoking an invitation, editing a custom role or its assignments, resetting a password, editing an account, and changing an SSO provider, an LDAP directory, a SCIM token, a group mapping or the org’s sign-in policy all answer
403for a token, whatever its role. It can still read them. Access a leaked token handed out would outlive the token’s revocation, so these stay with people. - Otherwise an
admintoken can do what an admin of its scope can do. Give automation the narrowest role that does the job.
It is not a virtual key (the data plane, /v1/*) and not a SCIM token (provisioning, /scim/v2/*); each is refused at the other’s door. See which key do I need.
In the dashboard#
Governance › API tokens lists the organization’s tokens with their scope, role, prefix, expiry, last use and state (active, expired or revoked), mints one (the secret is shown once, with a copy button), and rotates or revokes one after a confirmation. It takes the same roles as the API: minting, rotating and revoking need admin at the token’s own scope. A revoked or expired token cannot be rotated.
Mint a token#
Minting takes an admin of the token’s own scope: an org admin mints org-wide, team and project tokens, and a project admin mints tokens for that project only. A token therefore never holds more than the person who made it.
| Field | Meaning |
|---|---|
name | required, at most 80 characters; it is what the audit log shows |
team_id | scope the token to a team; omit both ids for an org-wide token |
project_id | scope the token to a project (its team, if named, must match) |
role | admin, member or viewer |
custom_role_id | an org-defined role of this organization instead; give exactly one of role and custom_role_id |
expires_in_days | 1 to 730; 90 when omitted |
never_expires | true opts out of the expiry; it cannot be combined with expires_in_days |
The response is the token row plus secret, a rolter_api_… value. The secret is shown once. Rolter stores only a peppered SHA-256 digest of it, the same way it stores sessions and virtual keys, so a lost secret is rotated, not looked up.
Use it like any control-plane credential:
List, rotate and revoke#
| Request | Does |
|---|---|
GET /api/v1/orgs/{org_id}/api-tokens | lists the organization’s tokens, revoked and expired ones included, with the token_prefix, scope, role, expiry and last_used_at; never a secret |
POST /api/v1/api-tokens/{id}/rotate | returns a new secret; the old one stops working in the same instant. A revoked or expired token answers 409 api_token_inactive |
DELETE /api/v1/api-tokens/{id} | revokes the token; it stops resolving on its next request |
An org admin lists every token of the organization; a team or project admin lists the tokens of the scopes they administer. A token also stops working when it expires, when its organization, team or project is deleted, or when its custom role is deleted.
A token outlives the person who minted it, so revoke the tokens of anyone who leaves: created_by names the minter.
Audit#
Minting, rotating and revoking write api_token.create, api_token.rotate and api_token.revoke to the organization’s audit log, naming the token and its scope but never the secret. Everything else a token does that is audited has no actor account and carries the token’s id and name in detail.api_token, so a pipeline’s changes are told apart from a person’s and from another pipeline’s.