+++
title = "Using Bearer Authentication"
weight = 95
updated = 2026-10-07
aliases = ["/docs/api/authentication/using-bearer-authentication/"]

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

{{ legacy_api_notice() }}

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/legacy/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/legacy/errors/401-unauthorized/index.md) error.