> ## Documentation Index
> Fetch the complete documentation index at: https://docs.turso.tech/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
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.
```bash cURL (org-scoped) theme={null}
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"}'
```
```bash cURL (deprecated, unrestricted) theme={null}
curl -L -X POST https://api.turso.tech/v1/auth/api-tokens/{tokenName} \
-H 'Authorization: Bearer TOKEN'
```
```bash cURL (group-scoped, presets) theme={null}
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"]
}'
```
```bash cURL (group-scoped, fine-grained) theme={null}
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"]
}'
```
```ts Node.js theme={null}
import { createClient } from "@tursodatabase/api";
const turso = createClient({
org: "...",
token: "",
});
const apiToken = await turso.apiTokens.create("my-token");
```
## OpenAPI
````yaml POST /v1/auth/api-tokens/{tokenName}
openapi: 3.0.1
info:
title: Turso Platform API
description: API description here
license:
name: MIT
version: 0.1.0
servers:
- url: https://api.turso.tech
description: Turso's Platform API
security: []
paths:
/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: 8a168b3c-f130-4741-bf10-0af459f439c4
id: 8baf30ce-9b49-4142-b2f1-88d7e77d7007
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: ...
components:
parameters:
tokenName:
name: tokenName
in: path
required: true
schema:
type: string
description: The name of the api token.
````