Skip to main content
To create a new API token, scoped to a single organization, run the following command:
Unrestricted (cross-org) tokens — minting without --org — are deprecated and will be removed in a future release. Always pass --org for new tokens. Existing unrestricted tokens continue to work for now, but you should rotate them to scoped tokens at your earliest convenience.

Flags

Organization-scoped tokens

Pass --org to restrict a token to a single organization:
An org-scoped token can only manage resources (groups, databases, members) within that organization. Requests to any other organization will be rejected. Without scopes, the token can do everything that you can do in the organization. Add --scope to limit it. The scopes then apply to every group in the organization:
An org-scoped token accepts all the group scopes, and also the organization scopes that follow. A token with scopes cannot manage members or invites, change organization settings, transfer groups or databases, or mint API tokens.

Organization scopes

These scopes are valid only on org-scoped tokens, that is, without --group: Reading invites and audit logs also requires that you are an admin or owner of the organization. --full-access does not include these scopes. To grant them, list each scope with --scope.

Group-scoped tokens

A group-scoped token is pinned to a single group inside an organization and is restricted to an explicit set of operations. It’s the right shape for automations that should be able to provision and manage databases inside one group without being able to touch the rest of the organization. You must be an admin or owner of the organization to mint a group-scoped token.

Available scopes

--scope can be repeated and accepts any of the following:
db:mint-token and db:rotate-creds are deliberately separate scopes. Minting a new SQL credential is additive; rotating invalidates every credential currently in use, which can take down running applications. Grant rotation only to automations that need it.
--scope, --read-only, and --full-access are mutually exclusive — pass one flavor at a time. Unknown scope labels are rejected before the request is sent. Group create, group delete, group transfer, and AWS migration are never reachable from a group-scoped token at any scope.

Lifecycle

Group-scoped tokens are pinned by the group’s UUID, not its name. Deleting a group, or transferring it to another organization, cascades a revoke to every token scoped to it. A new group created with the same name does not inherit tokens from the previous one.
The token value is only shown once at creation time. Store it somewhere safe.