TUturso

Create API Token

Changed on

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, and optionally scopes. The token can only act on resources inside that organization. With scopes, it can do only the listed operations, in every group of the 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}

Request

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 the token. Each entry is either an individual scope or one of the presets read-only (expands to read) and full-access (expands to every group scope, without group:create, group:delete, and org:read). Required and must be non-empty when group is set. Optional for an org-scoped token: without scopes, the token can do everything that its user can do in the organization. group:create, group:delete, and org:read are valid only on org-scoped tokens. 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

  • 328d56b8a9eaRevision changes
    • info

      added the new group:create enum value to the request property /

    • info

      added the new group:delete enum value to the request property /

    • info

      added the new org:read enum value to the request property /