Scoped API Tokens

API tokens let you authenticate FoundryDB API calls from scripts, CI pipelines, and third-party tools without using your account password. Tokens can be restricted to a precise set of permissions so a leaked token causes minimal damage.

For the full scope taxonomy and enforcement details, see API Token Scopes. This page covers the organizational management layer: how org owners and admins can audit and revoke every member's tokens.

Creating a Token

Any authenticated user can create tokens for themselves:

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", "backups:read"]
  }'

The response contains the token secret in the token field. It is shown exactly once. Store it in your secrets manager immediately.

{
  "token": "fdb_live_xxxxxxxxxxxxxxxxxxxxxxxx",
  "token_info": {
    "id": "f1a2b3c4-0000-0000-0000-000000000080",
    "token_name": "ci-deploy",
    "scopes": ["services:write", "backups:read"],
    "is_active": true,
    "created_at": "2026-06-01T12:00:00Z"
  }
}

Scope Reference

A scope is written as family:level. Levels are cumulative: write includes read, and admin includes write.

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

The wildcard * grants full access. Tokens with wildcard scope can also create new tokens. Scoped (non-wildcard) tokens cannot create or revoke other tokens, so a narrow token cannot escalate itself.

Routes outside the scoped families (organization management, alerts, admin, MFA) always require wildcard access.

Common Recipes

Read-only monitoring

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

CI deploy without delete

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

Backup automation

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

MCP server / AI assistant

The FoundryDB MCP server needs read access to services and can optionally create services. Use wildcard * only if the assistant needs full control.

{ "token_name": "mcp-assistant", "scopes": ["services:write", "backups:read"] }

Listing Your Tokens

curl -u user:password https://api.foundrydb.com/auth/tokens

Token secrets are never returned. You can see the name, scopes, active status, and last-used timestamp.

Revoking Your Own Token

curl -u user:password -X DELETE \
  https://api.foundrydb.com/auth/tokens/{token-id}

Revocation takes effect immediately on the next request.

Organization Token Oversight

Owners and admins can list every token held by any member of their organization:

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

Each entry includes the token ID, name, scopes, active status, last-used timestamp, and the member's username and email.

{
  "tokens": [
    {
      "id": "f1a2b3c4-0000-0000-0000-000000000080",
      "token_name": "ci-deploy",
      "scopes": ["services:write", "backups:read"],
      "is_active": true,
      "last_used_at": "2026-06-02T08:15:00Z",
      "username": "alice",
      "email": "alice@acme.com"
    }
  ]
}

To revoke a member's token from the organization:

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

The token must belong to a current member of the organization. Revocation is immediate.

Token Rotation

There is no in-place rotation endpoint. The recommended pattern is:

1. Create a new token with the same scopes.
2. Update the secret in your deployment environment.
3. Confirm the new token is working.
4. Revoke the old token.

This avoids a gap in service coverage during the rotation.

Dashboard

The API Tokens tab in your account settings lets you create and revoke your own tokens with a visual scope picker. Organization owners and admins have an additional tab under organization settings to review and revoke member tokens.