API Tokens

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

auth

api-tokens

{tokenName}

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"}'

{
  "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 -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

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:

"..."

List Validate