> ## 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.

# Authentication

The Turso API uses API tokens to authenticate requests. You can create and revoke API tokens using the [Turso CLI](/cli) and [Authentication API](/api-reference/tokens/create).

Tokens can be minted at three levels of restriction:

| Restriction                 | What it can do                                                                | How to mint                                                                    |
| --------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| Organization-scoped         | Restricted to a single organization.                                          | `turso auth api-tokens mint my-token --org my-org`                             |
| Group-scoped                | Pinned to one group inside an organization, with a chosen set of permissions. | `turso auth api-tokens mint my-token --org my-org --group default --read-only` |
| Unrestricted *(deprecated)* | Acts on every organization the caller belongs to.                             | `turso auth api-tokens mint my-token`                                          |

<Warning>
  **Unrestricted (cross-org) tokens are deprecated and will be removed in a future release.** New tokens should always be scoped to an organization with `--org`. Existing unrestricted tokens continue to work for now, but you should rotate them to scoped tokens at your earliest convenience.
</Warning>

```bash theme={null}
# Token scoped to a single organization
turso auth api-tokens mint my-token --org my-org

# Group-scoped token, read-only (tighter scope, for automations that only need one group)
turso auth api-tokens mint my-token --org my-org --group default --read-only

# Token with access to all organizations — deprecated
turso auth api-tokens mint my-token
```

* Scope tokens to a single organization with `--org`, especially in CI/CD and production environments.
* Use environment variables when working with API tokens.
* Never share your API token in public, including repositories, and CI/CD Actions.

Turso uses Bearer authentication, and requires your API token to be passed with all protected requests in the `Authorization` header:

```bash theme={null}
Authorization: Bearer TOKEN
```

## Group-scoped tokens

A group-scoped token is a Platform API credential pinned to one group inside an organization, with an explicit list of allowed operations. It's the right shape for automations that should be able to provision and manage databases inside a single group without being able to reach the rest of the organization.

The caller minting a group-scoped token must be an admin or owner of the organization.

<Note>
  Group-scoped tokens are control-plane credentials — they authorize requests to the Turso Platform API. They are independent from the [SQL-engine tokens](/sdk/authorization/tokens) that your application uses to query a database. The two systems do not share key material or vocabulary.
</Note>

### Scope vocabulary

The platform expands the presets `read-only` and `full-access` to the corresponding individual scopes server-side, so the values you see on a token after creation are always individual scopes.

| Scope                | Allows                                                                                                |
| -------------------- | ----------------------------------------------------------------------------------------------------- |
| `read`               | All GET-style routes: list/retrieve databases and groups, configuration, usage, instances, locations. |
| `db:create`          | Create databases inside the group (`POST /databases`), seed from a dump, restore.                     |
| `db:delete`          | Delete a database inside the group.                                                                   |
| `db:configure`       | Patch database configuration, transfer, wake, add or remove instances.                                |
| `db:mint-token`      | Issue a SQL-engine token or TLS client certificate for a database inside the group.                   |
| `db:rotate-creds`    | Rotate the database signing key, invalidating every SQL token previously issued for it.               |
| `group:configure`    | Configure, rename, update, unarchive the group, or add and remove locations.                          |
| `group:mint-token`   | Issue a group-level SQL-engine token.                                                                 |
| `group:rotate-creds` | Rotate the group signing key, invalidating every SQL token issued against any database in the group.  |

<Warning>
  `db:mint-token` and `db:rotate-creds` are deliberately separate scopes. Minting a new SQL credential is additive; rotating invalidates every credential currently in use, which can take down running applications. Grant rotation only to automations that need it.
</Warning>

### Presets

| Preset        | Expands to                           |
| ------------- | ------------------------------------ |
| `read-only`   | `read`                               |
| `full-access` | Every individual scope listed above. |

Group create, group delete, group transfer, and AWS migration are intentionally not reachable from a group-scoped token at any scope — those operations are gated to organization-level credentials.

### Lifecycle

* Group-scoped tokens are pinned by the group's UUID, not its name. If a group is deleted and a new one is created with the same name, old tokens do not transfer — they are revoked along with the group.
* Deleting a group cascades a revoke to every token scoped to it.
* Transferring a group to a different organization cascades a revoke to every token scoped to it.

### Managing organization tokens

Two endpoints let admins manage every token scoped to an organization in one place — they are what backs the dashboard's organization-level token table:

* [`GET /v1/organizations/{organizationSlug}/api-tokens`](/api-reference/tokens/list-organization) — list every org-scoped and group-scoped token, with the minting user attached.
* [`DELETE /v1/organizations/{organizationSlug}/api-tokens/{tokenId}`](/api-reference/tokens/revoke-organization) — revoke by ID.

Members and viewers can call the same endpoints, but only see and revoke tokens they minted themselves.

## Base URL

The Turso API is located at the following URL:

```bash theme={null}
https://api.turso.tech
```