+++
title = "API Authentication"
weight = 86
updated = 2026-11-18

[extra]
nav_title = "Authentication"
weight = 25
+++

Every request to the Bonsai API v1 needs an [API token](@/docs/account/api-tokens/index.md), sent as a Bearer token in the `Authorization` header:

```bash
curl https://api.bonsai.io/v1/account \
  -H "Authorization: Bearer bonsai_<key>_<secret>"
```

Only one operation takes no token: [`GET /v1`](@/docs/api/reference/account/index.md#get-api-root).

## Tokens

A token looks like `bonsai_<key>_<secret>`. The **key** is its public half, which the dashboard's API Tokens list shows so you can tell tokens apart. The **secret** is shown once, when the token is created. [Creating an API token](@/docs/account/api-tokens/index.md) covers making one in the dashboard, its expiration, and keeping it safe.

v1 takes Bearer authentication only. Basic authentication works on the [legacy API](@/docs/api/legacy/_index.md) only, but the same token works on both.

### Tokens created before the `bonsai_` format

Tokens from before the `bonsai_` format have a separate key and secret. They keep working. On v1, send them joined by a dot:

```
Authorization: Bearer <key>.<secret>
```

### Who a token belongs to

A token belongs to the account, not to the person who created it. It keeps working, with its scopes, if that person leaves the account or changes role, until an Admin revokes it.

### The calling token

`GET /v1/token` shows the token making the request: its key, name, account, scopes and expiry. `DELETE /v1/token` revokes it, as revoking it in the dashboard does. Neither needs a scope, since a token only ever reaches itself. See [Account and tokens](@/docs/api/reference/account/index.md#get-token).

## Scopes

A token's scopes decide which operations it can call. Each operation that takes a token needs one scope, except [`GET /v1/token`](@/docs/api/reference/account/index.md#get-token) and [`DELETE /v1/token`](@/docs/api/reference/account/index.md#revoke-token), which any valid token can call on itself:

| Scope | What it allows | Operations |
| --- | --- | --- |
| `account:read` | Read the account, and list the plans, regions, spaces and releases available to it. | [`GET /v1/account`](@/docs/api/reference/account/index.md#get-account), [`GET /v1/plans`](@/docs/api/reference/catalog/index.md#list-plans), [`GET /v1/plans/{plan_id}`](@/docs/api/reference/catalog/index.md#get-plan), [`GET /v1/regions`](@/docs/api/reference/catalog/index.md#list-regions), [`GET /v1/spaces`](@/docs/api/reference/catalog/index.md#list-spaces), [`GET /v1/releases`](@/docs/api/reference/catalog/index.md#list-releases) |
| `clusters:read` | List and read the account's clusters, with their Actions, usage and metrics. | [`GET /v1/clusters`](@/docs/api/reference/clusters/index.md#list-clusters), [`GET /v1/clusters/{cluster_id}`](@/docs/api/reference/clusters/index.md#get-cluster), [`GET .../actions`](@/docs/api/reference/actions/index.md#list-cluster-actions), [`GET /v1/actions/{action_id}`](@/docs/api/reference/actions/index.md#get-action), [`GET .../usage`](@/docs/api/reference/usage-and-metrics/index.md#get-cluster-usage), [`GET .../metrics`](@/docs/api/reference/usage-and-metrics/index.md#get-cluster-metrics) |
| `clusters:write` | Create, rename and delete clusters, and change their plans. | [`POST /v1/clusters`](@/docs/api/reference/clusters/index.md#create-cluster), [`PATCH /v1/clusters/{cluster_id}`](@/docs/api/reference/clusters/index.md#update-cluster), [`DELETE /v1/clusters/{cluster_id}`](@/docs/api/reference/clusters/index.md#delete-cluster), [`POST .../plan_changes`](@/docs/api/reference/clusters/index.md#change-cluster-plan) |
| `credentials:read` | List and read the account's cluster credentials, passwords included. | [`GET .../credentials`](@/docs/api/reference/credentials/index.md#list-cluster-credentials), [`GET .../credentials/{credential_id}`](@/docs/api/reference/credentials/index.md#get-cluster-credential) |
| `credentials:write` | Create and revoke cluster credentials. | [`POST .../credentials`](@/docs/api/reference/credentials/index.md#create-cluster-credential), [`DELETE .../credentials/{credential_id}`](@/docs/api/reference/credentials/index.md#revoke-cluster-credential) |
| `data:read` | Read what is in the account's clusters, through the [hosted MCP server](@/docs/agents/hosted-mcp/index.md): indices, documents and searches. | None. See [the data scopes](#data-scopes) |
| `data:write` | Read and change what is in the account's clusters, through the hosted MCP server: create and delete indices, add and remove documents. | None. See [the data scopes](#data-scopes) |
| `query_logs:read` | Read the top search queries sent to the account's clusters. | [`GET .../queries`](@/docs/api/reference/usage-and-metrics/index.md#get-cluster-top-queries) |

`.../` stands for `/v1/clusters/{cluster_id}/`. `clusters:write` needs the Admin role on the account.

The first three scopes also cover the matching calls of the [legacy API](@/docs/api/legacy/_index.md). The others work on v1 only. Tokens made before they existed don't have them, and new tokens get them only when picked. Give each token only the scopes it needs: credentials carry passwords, and query logs hold your users' search terms.

### The data scopes {#data-scopes}

`data:read` and `data:write` allow no API operation. They are for the [hosted MCP server](@/docs/agents/hosted-mcp/index.md), whose `cluster_request` tool sends requests to a cluster's own API: it refuses a token with neither, and sends only `GET` and `HEAD` requests for a token without `data:write`.

The server reaches a cluster with the cluster's credential, which it reads from this API. So a token given a data scope is given `credentials:read` with it, and a role that can't hold `credentials:read` can't hold a data scope.

That makes the data scopes a statement of what an app may do, which the tool keeps to, and not a separate lock: the same token can read a cluster's password from [`GET .../credentials/{credential_id}`](@/docs/api/reference/credentials/index.md#get-cluster-credential). Give one only where you would give `credentials:read`.

## When authentication fails

- A request without a valid token gets a [`401 unauthorized`](@/docs/api/errors/index.md#unauthorized): the header is missing or doesn't use `Bearer`, or the token is unknown, revoked or expired.
- A request the token has no scope for gets a [`403 missing_scope`](@/docs/api/errors/index.md#missing_scope). Its `details[].scope` names the scope it needs.
- Too many failed authentications from one IP address get a [`429 too_many_failed_authentications`](@/docs/api/errors/index.md#too_many_failed_authentications).
