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.
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.
