+++
title = "Using Basic Authentication"
weight = 94
updated = 2026-10-07
aliases = ["/docs/using-basic-authentication.html", "/docs/bonsai-api/authentication/using-basic-authentication/", "/docs/api/authentication/using-basic-authentication/"]

[extra]
nav_title = "Using Basic Authentication"
weight = 20
+++

The Bonsai API supports HTTP Basic Authentication over TLS >= 1.2 as one means for authenticating requests.

{{ legacy_api_notice() }}

The Bonsai API supports [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) over TLS >= 1.2 as one means for authenticating requests. The authentication protocol utilizes an `Authorization` header, with the contents: `Basic <base64 of username:password>`.

Many tools, such as curl, will construct this header automatically from credentials in a URL or the `-u` flag. For example, curl will translate `https://user:pass@api.bonsai.io/` into a request to `https://api.bonsai.io/` with the header `Authorization: Basic dXNlcjpwYXNz`.

## Credentials

For Basic Auth, the token key corresponds to the "user" parameter and the token secret corresponds to the "password" parameter. This works for every token, whether it was created before or after the `bonsai_` format:

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

A token in the `bonsai_<key>_<secret>` format can also be sent whole as the password. The username is then ignored, so it can be anything:

```bash
curl -u "token:bonsai_<key>_<secret>" https://api.bonsai.io/clusters
```

See [Creating an API Token](@/docs/account/api-tokens/index.md) for how a token splits into its key and secret. To send a token without encoding it, use [Bearer authentication](@/docs/api/legacy/authentication/using-bearer-authentication/index.md) instead.