Sign in

Create API Token

Returns a new API token belonging to a user.

The token can be minted at three levels of restriction, in increasing order of narrowness:

  • Organization-scoped — pass organization. The token can only act on resources inside that organization.
  • Group-scoped — pass organization, group, and scopes. The token is pinned to a single group inside the organization and only the operations listed in scopes are allowed. The caller must be an admin or owner of the organization.
  • Unrestricted (deprecated) — no request body. The token can act on every organization the caller belongs to. Unrestricted tokens are deprecated and will be removed in a future release. Always pass organization for new tokens and rotate existing unrestricted tokens to scoped tokens.

Group-scoped tokens are designed for automations that should be able to provision and manage databases inside a single group without being able to touch the rest of the organization.

post/v1/auth/api-tokens/{tokenName}

Path parameters

tokenNamestring required

The name of the api token.

Request body

organizationstring

The organization slug to restrict this token to. Required when group is set.

groupstring

The group name (inside organization) to restrict this token to. Requires organization and a non-empty scopes list.

scopesstring[]

Permissions to grant a group-scoped token. Each entry is either an individual scope or one of the presets read-only (expands to read) and full-access (expands to every scope). Required and must be non-empty when group is set. db:mint-token lets the token issue new SQL credentials; db:rotate-creds invalidates every existing SQL token for the database — they are deliberately separate because rotation is destructive.

Example request

{
  "organization": "my-org",
  "group": "default",
  "scopes": [
    "db:create",
    "db:configure",
    "db:mint-token"
  ]
}

Response

Successful response

nameName — unresolved $ref
idId — unresolved $ref
tokenstring

The actual token contents as a JWT. This is used with the Bearer header, see Authentication for more details. This token is never revealed again.

Changes