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

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",
    "scopes": ["org:read"]
  }'

curl -L -X POST https://api.turso.tech/v1/auth/api-tokens/{tokenName} \
  -H 'Authorization: Bearer TOKEN'

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",
    "group": "default",
    "scopes": ["read-only"]
  }'

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",
    "group": "default",
    "scopes": ["db:create", "db:configure", "db:mint-token"]
  }'

import { createClient } from "@tursodatabase/api";

const turso = createClient({
  org: "...",
  token: "",
});

const apiToken = await turso.apiTokens.create("my-token");

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

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

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

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",
    "scopes": ["org:read"]
  }'

curl -L -X POST https://api.turso.tech/v1/auth/api-tokens/{tokenName} \
  -H 'Authorization: Bearer TOKEN'

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",
    "group": "default",
    "scopes": ["read-only"]
  }'

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",
    "group": "default",
    "scopes": ["db:create", "db:configure", "db:mint-token"]
  }'

import { createClient } from "@tursodatabase/api";

const turso = createClient({
  org: "...",
  token: "",
});

const apiToken = await turso.apiTokens.create("my-token");

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

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",
    "scopes": ["org:read"]
  }'

curl -L -X POST https://api.turso.tech/v1/auth/api-tokens/{tokenName} \
  -H 'Authorization: Bearer TOKEN'

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",
    "group": "default",
    "scopes": ["read-only"]
  }'

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",
    "group": "default",
    "scopes": ["db:create", "db:configure", "db:mint-token"]
  }'

import { createClient } from "@tursodatabase/api";

const turso = createClient({
  org: "...",
  token: "",
});

const apiToken = await turso.apiTokens.create("my-token");

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 (optionally with scopes) 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 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.

Available options:

read,

db:create,

db:delete,

db:configure,

db:mint-token,

db:rotate-creds,

group:configure,

group:mint-token,

group:rotate-creds,

group:create,

group:delete,

org:read,

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:

"..."

Turso Cloud

SDKs

CLI

API Reference

Integrations

Create API Token

Authorizations

Path Parameters

Body

Response