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}

cURL (org-scoped)

curl -L -X POST https://api.turso.tech/v1/auth/api-tokens/{tokenName} \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"organization": "my-org"}'

200

{
  "name": "<unknown>",
  "id": "<unknown>",
  "token": "..."
}

The token in the response is never revealed again. Store this somewhere safe, and never share or commit it to source control.

Unrestricted (cross-org) tokens are deprecated and will be removed in a future release. Always include at least organization in the request body.

cURL (org-scoped)

curl -L -X POST https://api.turso.tech/v1/auth/api-tokens/{tokenName} \
  -H 'Authorization: Bearer TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{"organization": "my-org"}'

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

tokenName · string · required

The name of the api token.

Body

application/json

Optional restriction for the token. Omit the body for an unrestricted token, pass organization alone for an org-scoped token, or pass organization + group + scopes for a group-scoped token.

organization · string

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

Example:

"my-org"

group · string

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

Example:

"default"

scopes · enum<string>[]

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.

Available options: read, db:create, db:delete, db:configure, db:mint-token, db:rotate-creds, group:configure, group:mint-token, group:rotate-creds, read-only, full-access

Example:

[
  "db:create",
  "db:configure",
  "db:mint-token"
]

Response

200 - application/json

Successful response

name · any

id · any

token · string

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.

Example:

"..."