+++
title = "Using Bearer Authentication"
weight = 75
updated = 2026-10-07

[extra]
nav_title = "Using Bearer Authentication"
weight = 30
+++

The Bonsai API supports Bearer authentication over TLS >= 1.2, sending an API token as it is in the `Authorization` header.

### Alpha Stage

{% admonition(title="Note") %}
The Bonsai API is currently in its Alpha release phase. It may not be feature-complete, and is subject to change without notice. If you have any questions about the roadmap of the API, please reach out to [support](mailto:support@bonsai.io).
{% end %}

With Bearer authentication, each request carries an `Authorization` header with the word `Bearer`, a space, and the token. The token takes one of two forms, depending on when it was created.

## Tokens in the `bonsai_` format

Send a token created in the `bonsai_<key>_<secret>` format exactly as the dashboard showed it:

```
Authorization: Bearer bonsai_<key>_<secret>
```

For example, with curl:

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

## Tokens created before the `bonsai_` format

A token created before the `bonsai_` format has a separate key and secret. Join them with a dot:

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

For example, with curl:

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

The same key and secret also work with [Basic authentication](@/docs/api/authentication/using-basic-authentication/index.md).

## Notes

- `Bearer` is not case-sensitive, but the token is.
- Send only the token after `Bearer`: no quotes, and nothing after it.
- Send one credential per request. A header with more than one credential, such as a Basic and a Bearer credential together, is refused with an [HTTP 401: Unauthorized](@/docs/api/errors/401-unauthorized/index.md) error.