+++
title = "Creating an API Token"
weight = 49
updated = 2026-11-18
aliases = ["/docs/creating-an-api-token.html", "/docs/account-and-organization-management/organization-account/api-tokens/"]

[extra]
nav_title = "API Tokens"
weight = 50
+++

An API token is required to use the [Bonsai API](@/docs/api/overview/index.md).

## Creating a token

Navigate to <a href="https://app.bonsai.io">your account</a>, open its settings, and click on the **API Tokens** tab. Then click on the **New Token** button. Only account Admins can create tokens.

The new token form has two settings: the token's **scopes** and its **expiration**. Click **Create Token** when you're done.

### Scopes

Scopes decide which API operations the token can call. Check one box per scope the token needs:

- `account:read` and `clusters:read` read the account, its clusters, and the plans and regions to create them with.
- `clusters:write` creates, changes and deletes clusters, as the [Terraform provider](@/docs/integrations/deploy-with-terraform/index.md) does.
- `credentials:read` and `credentials:write` read and manage cluster credentials, which carry passwords.
- `data:read` and `data:write` let an AI agent read, or read and change, what is in your clusters through the [hosted MCP server](@/docs/agents/hosted-mcp/index.md). Checking one adds `credentials:read` to the token.
- `query_logs:read` reads the top search queries, which hold your users' search terms.

A new token is read-only by default: `account:read` and `clusters:read` are checked, and the others are not. A token needs at least one scope. Tokens created before scopes existed hold `account:read`, `clusters:read` and `clusters:write`.

[API authentication](@/docs/api/authentication/index.md#scopes) lists every scope with the operations it allows.

### Expiration

A token can expire **30**, **90** or **365** days after it's created, or never. **No expiration** is selected by default.

An expired token stops working: requests made with it get a [`401 unauthorized`](@/docs/api/errors/index.md#unauthorized) error. It can't be renewed, so create a new token to replace it. Expired tokens stay in the list, marked **Expired**, until you revoke them.

Tokens created before expiration existed never expire.

## Copy your token right away

Once the token is created, the dashboard shows it **once**, at the top of the API Tokens page. Copy it and store it somewhere safe, like a password manager or your deployment's secret store. Bonsai keeps only a hash of the token's secret, so nobody, including Bonsai support, can show it to you again. If you lose it, revoke the token and create a new one.

A token looks like this:

```
bonsai_<key>_<secret>
```

For example, `bonsai_1a2b3c4d5e6f7a8b_0123456789abcdef0123456789abcdef0123456789abcdef`. The part between `bonsai_` and the second underscore is the token's **key**, which the API Tokens list shows so you can tell your tokens apart. The rest is its **secret**.

## Using your token

Send the token with each request as a Bearer token:

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

[API authentication](@/docs/api/authentication/index.md) covers tokens on the API, including tokens created before the `bonsai_` format. The [legacy API](@/docs/api/legacy/_index.md) also takes [Basic authentication](@/docs/api/legacy/authentication/using-basic-authentication/index.md). If a tool for the legacy API asks for a key and a secret separately, split the token at the underscores: the key is the part after `bonsai_`, and the secret is the part after the key.

## Token details

The API Tokens list shows, for each token: its key, when it was created and by whom, its scopes, when it expires, and when it was last used. A token whose creator has left the account is marked **left the account**. **Last used** is updated when the token authenticates a request, to within a minute.

Every time a token is used to make a request to the API, we create a log of which token was used, the auth method and owner of the token, and the IP address of the requester. The **API Requests** table under the token list shows these logs.

## Revoking a token

To revoke a token, click on its Revoke button. Admins can revoke any of the account's tokens. Once revoked, the token can no longer be used to access the API, and requests made with it get a [`401 unauthorized`](@/docs/api/errors/index.md#unauthorized) error. Revoking can't be undone. A token can also revoke itself, with `DELETE /v1/token`.

A token belongs to the account, not to the person who created it. If its creator leaves the account or changes role, the token keeps working, with the same scopes, until an Admin revokes it. When someone leaves, review the tokens they created, and revoke any they could still have a copy of.

## Keeping your token safe

Treat your token like a password. Do not hard-code it into applications, check it into source control, or share it. Give each token only the scopes it needs, and an expiration if it's only needed for a while.
