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

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.

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.