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