API Token Scopes

API tokens can be restricted to a precise set of permissions using scopes. A scoped token only grants access to the actions you allow, so you can hand a token to a CI pipeline or a monitoring system without giving it full control of your account.

Scope Format

A scope is written as family:level.

• Family identifies a group of resources: services, backups, pipelines, webhooks, or billing.
• Level controls how much you can do within that family. Levels are cumulative: read < write < admin.

Level	Includes
read	Read operations (GET)
write	Everything in read, plus create and update
admin	Everything in write, plus delete

The wildcard scope * grants full access to every family at every level. If you create a token without specifying any scopes, the wildcard is stored explicitly, so existing integrations keep working unchanged.

Creating a Scoped Token

curl -u user:password -X POST https://api.foundrydb.com/auth/tokens \
  -H "Content-Type: application/json" \
  -d '{
    "token_name": "ci-deploy",
    "scopes": ["services:write"]
  }'

A successful request returns 201 Created with the one-time token secret and a token_info object describing the granted scopes:

{
  "token": "fdb_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  "token_info": {
    "token_name": "ci-deploy",
    "scopes": ["services:write"]
  }
}

The token secret is shown only once. Store it securely, it cannot be retrieved again.

If any scope is not recognized, the request fails with 400 Bad Request and no token is created.

Enforcement

Every API request is checked against the token's scopes. If a token lacks the scope required for an action, the request is rejected with 403 Forbidden:

{
  "error": "token does not have the required scope",
  "required_scope": "services:write"
}

Backup Sub-Resources Use the backups Family

Backups, backup schedules, restore operations, and point-in-time recovery (PITR) are sub-resources of a service, but they are governed by the backups family, not services. A token that manages services does not automatically manage their backups, and vice versa. Grant the backups scope explicitly when a token needs to work with backups.

Actions Scoped Tokens Cannot Perform

For safety, scoped tokens are never allowed to:

• Create or revoke other API tokens.
• Manage organizations, members, or infrastructure credentials.

These actions require a full-access token or an authenticated dashboard session.

Scope Reference

The diagram below shows how the API authorizer evaluates an incoming token request in real time. The example token carries services:write and backups:read. Because levels are cumulative, services:write satisfies a services:read check. Requests requiring services:admin or backups:write are denied with 403 insufficient_scope.

Scoped token enforcement

VERDICT token: services:write + backups:read

Scoped Tokenservices:write · backups:readauthorize →

services:read200services:write200services:admin403backups:read200backups:write403

Organization (mints)Scoped tokenGranted scopeAPI authorizer200 allowed403 insufficient_scope

Family	read	write	admin
services	List and view services, nodes, users	Create and update services, scale, manage users	Delete services and nodes
backups	List and view backups, schedules, PITR status	Create backups, configure schedules, run restores	Delete backups and schedules
pipelines	List and view pipelines	Create and update pipelines	Delete pipelines
webhooks	List and view webhooks	Create and update webhooks	Delete webhooks
billing	View invoices and usage	Update billing settings	Remove billing methods

Example Token Recipes

Read-only monitoring

A dashboard that only needs to read service health and metrics:

{ "token_name": "grafana", "scopes": ["services:read"] }

CI deploys without delete

A pipeline that provisions and updates services but must never delete them:

{ "token_name": "ci-deploy", "scopes": ["services:write"] }

Backups only

An automation that triggers and restores backups but cannot touch the services themselves:

{ "token_name": "backup-runner", "scopes": ["backups:admin"] }

Organization Oversight

Organization owners and admins can review and revoke the tokens created by their members.

List every member token in the organization, with its scopes and last-used timestamp:

curl -u user:password \
  https://api.foundrydb.com/organizations/{orgId}/tokens

Revoke a token:

curl -u user:password -X DELETE \
  https://api.foundrydb.com/organizations/{orgId}/tokens/{tokenId}

A revoked token stops working immediately on the next request.

Token Lifecycle and Security

Token format

Tokens follow the format fdb_live_<random>. The secret is shown exactly once at creation time. FoundryDB does not store it in retrievable form; if you lose it, create a new token and revoke the old one.

Rotation

Rotate tokens periodically or whenever there is any suspicion of exposure. Create the replacement token before revoking the old one to avoid downtime:

1. Create a new token with the same scopes as the token being replaced.
2. Update your integration to use the new token secret.
3. Verify the integration is working.
4. Revoke the old token.

Least-privilege principle

Issue separate tokens for separate consumers. A monitoring system needs only services:read; a CI pipeline that provisions services needs services:write; a backup automation needs backups:admin. Granting the wildcard * scope to a long-lived token is a risk: if the token is leaked, every resource family and level is exposed.

Expiry and audit

Tokens do not expire automatically. Owners and admins can see every member's active tokens along with their last-used timestamp via the organization oversight endpoints. Revoke tokens that have not been used for an extended period.

Dashboard

You do not need the API to manage scopes. When you create a token in the dashboard, the token creation dialog includes a scope picker so you can select families and levels visually. Organization owners and admins can review and revoke member tokens from the API Tokens tab in organization settings.