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": "..."
}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 optionallyscopes. The token can only act on resources inside that organization. Withscopes, it can do only the listed operations, in every group of the organization. - Group-scoped — pass
organization,group, andscopes. The token is pinned to a single group inside the organization and only the operations listed inscopesare 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
organizationfor 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.
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": "..."
}token in the response is never revealed again. Store this somewhere safe, and never share or commit it to source control.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
Body
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.
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.
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 [
"db:create",
"db:configure",
"db:mint-token"
]
Response
Successful response
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.
"..."
Was this page helpful?