Turso Auth API
The Auth API from Turso — 3 operation(s) for auth.
OpenAPI Specification
openapi: 3.0.1
info:
title: Turso Platform Auth API
description: API description here
license:
name: MIT
version: 0.1.0
servers:
- url: https://api.turso.tech
description: Turso's Platform API
tags:
- name: Auth
paths:
/v1/auth/validate:
get:
summary: Validate API Token
description: Validates an API token belonging to a user.
operationId: validateAPIToken
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
exp:
type: integer
description: The time of expiration for the provided token in unix epoch seconds, or `-1` if there is no expiration.
example: 999
tags:
- Auth
/v1/auth/api-tokens:
get:
summary: List API Tokens
description: Returns a list of API tokens belonging to a user.
operationId: listAPITokens
responses:
'200':
description: Successful response
content:
application/json:
schema:
type: object
properties:
tokens:
type: array
items:
$ref: '#/components/schemas/APIToken'
tags:
- Auth
/v1/auth/api-tokens/{tokenName}:
post:
summary: Create API Token
description: '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.'
operationId: createAPIToken
parameters:
- $ref: '#/components/parameters/tokenName'
requestBody:
description: 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.
required: false
content:
application/json:
schema:
type: object
properties:
organization:
type: string
description: The organization slug to restrict this token to. Required when `group` is set.
example: my-org
group:
type: string
description: The group name (inside `organization`) to restrict this token to. Requires `organization` and a non-empty `scopes` list.
example: default
scopes:
type: array
items:
type: string
enum:
- 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
description: 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.
example:
- db:create
- db:configure
- db:mint-token
responses:
'200':
description: Successful response
content:
application/json:
schema:
properties:
name:
$ref: '#/components/schemas/APIToken/properties/name'
id:
$ref: '#/components/schemas/APIToken/properties/id'
token:
type: string
description: The actual token contents as a JWT. This is used with the `Bearer` header, see [Authentication](/authentication) for more details. **This token is never revealed again.**
example: '...'
tags:
- Auth
delete:
summary: Revoke API Token
description: Revokes the provided API token belonging to a user.
operationId: revokeAPIToken
parameters:
- $ref: '#/components/parameters/tokenName'
responses:
'200':
description: Successful response
content:
application/json:
schema:
properties:
token:
type: string
description: The revoked token name.
example: '...'
tags:
- Auth
components:
schemas:
APIToken:
type: object
properties:
name:
type: string
description: The name given to the API Token.
example: my-token
id:
type: string
description: The ID generated by Turso for the API Token.
example: clGFZ4STEe6fljpFzIum8A
organization:
type: string
description: The organization slug this token is restricted to. Omitted if the token has access to all organizations.
example: my-org
group:
type: string
description: The group name this token is pinned to. Present only for group-scoped tokens.
example: default
scopes:
type: array
items:
type: string
description: The expanded list of scopes granted to this token. Present only for group-scoped tokens. Presets passed at creation time (`read-only`, `full-access`) are stored as the underlying individual scopes and are returned in that form.
example:
- db:create
- db:configure
- db:mint-token
created_at:
type: string
description: The date the token was created, in `YYYY-MM-DD` format.
example: '2026-05-21'
parameters:
tokenName:
name: tokenName
in: path
required: true
schema:
type: string
description: The name of the api token.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT