Skip to main content
Scopes are the permission strings you attach to a token when you create it. Each scope grants the token holder the ability to perform a specific category of action against the Tooken API. By combining only the scopes a service requires, you enforce the principle of least privilege — limiting what an attacker can do if a token is ever leaked.

​
Why scopes matter

Without scope enforcement, every token would carry full access to your Tooken account. A single leaked credential could let an attacker read audit trails, create backdoor tokens, or revoke your entire token inventory. Scopes eliminate that risk by making every token’s authority explicit and minimal. When Tooken evaluates an inbound request, it checks whether the presented token carries the scope required for that operation. If the scope is missing, Tooken rejects the request immediately — before any data is accessed or changed.

​
Available scopes

ScopeDescription
tokens:readList and view tokens
tokens:writeCreate new tokens
tokens:revokeRevoke existing tokens
tokens:rotateRotate token secrets
audit:readView audit logs
webhooks:readView webhook configurations
webhooks:writeCreate and update webhooks
Scopes are additive — a token can carry any combination of the above. There is no inheritance between scopes: holding tokens:write does not imply tokens:read.

​
Assigning scopes when creating a token

Pass a scopes array in the request body when calling POST /tokens. Include exactly the scopes the service needs — nothing more. 
curl --request POST \
  --url https://api.tooken.io/v1/tokens \
  --header 'Authorization: Bearer tok_live_xxxxxxxxxxxxxxxxxxxx' \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "audit-reporter",
    "scopes": ["tokens:read", "audit:read"],
    "expires_at": "2025-12-31T23:59:59Z"
  }'
Tooken validates the scopes array at creation time and rejects unknown or malformed scope strings with a 400 Bad Request.

​
What a scope error looks like

When a token makes a request that requires a scope it does not have, Tooken returns a 403 Forbidden response:
403 response
{
  "error": "forbidden",
  "message": "Token missing required scope: tokens:write"
}
Use this response to identify which scope to add — or to confirm that a service is attempting an operation it should not be permitted to perform.
Do not assign broad scope sets to production tokens as a convenience measure. A token with tokens:write and tokens:revoke can create new backdoor tokens or destroy your entire token inventory if compromised. Always audit the scopes on each token before deploying.

​
Scope patterns by service role

Group scopes around a service’s actual role to keep your permission model readable and auditable:
  • Read-only reporter (dashboards, monitoring): tokens:read, audit:read
  • CI/CD pipeline (deploy automation): tokens:rotate, webhooks:read
  • Token provisioner (internal tooling that issues tokens): tokens:write, tokens:read
  • Incident responder (emergency revocation): tokens:revoke, audit:read
  • Webhook manager: webhooks:read, webhooks:write
Naming your tokens after the role (e.g., incident-responder) makes it obvious at a glance what each token should and should not be able to do.

​
Viewing and updating scopes

You can inspect the scopes on any token at any time from the Tooken dashboard or by calling GET /tokens/:id. Scopes are fixed at creation — to change a token’s scopes, revoke it and issue a new token with the correct scope set. This ensures a clean audit trail every time permissions change.

Token anatomy

Understand the full token object, lifecycle states, and how to create tokens.

Expiration and rotation

Learn how to set expiration dates and rotate secrets without changing token IDs.