+++
title = "Legacy API Authentication"
weight = 93
updated = 2026-10-07
aliases = ["/docs/authentication.html", "/docs/bonsai-api/authentication/overview/", "/docs/api/authentication/using-hmac-authentication/", "/docs/using-hmac-authentication.html", "/docs/bonsai-api/authentication/using-hmac-authentication/", "/docs/api/authentication/overview/"]

[extra]
nav_title = "Overview"
weight = 5
+++

The Bonsai API supports two methods of authenticating requests: Bearer authentication, and HTTP Basic Auth.

{{ legacy_api_notice() }}

Every request to the API must carry an [API token](@/docs/account/api-tokens/index.md) in its `Authorization` header, using one of two schemes:

- [**Bearer authentication**](@/docs/api/legacy/authentication/using-bearer-authentication/index.md): `Authorization: Bearer bonsai_<key>_<secret>`. This is the simplest option for a new token.
- [**HTTP Basic Auth**](@/docs/api/legacy/authentication/using-basic-authentication/index.md): the token's key and secret as the username and password. Most HTTP clients support it out of the box.

Both schemes accept new `bonsai_` tokens as well as the key and secret pairs of tokens created before that format. Send one credential per request: a request with more than one, such as both a Basic and a Bearer credential, is refused.

Both schemes send the token as it is, so only use them over https. Requests to `https://api.bonsai.io` are encrypted with TLS.

#### **Failed Authentication**

Requests that do not have the proper authentication will receive an [HTTP 401: Unauthorized](@/docs/api/legacy/errors/401-unauthorized/index.md) response. This can happen for a variety of reasons, including (but not limited to):

1. The `Authorization` header is missing, or uses a scheme other than `Basic` or `Bearer`
2. The token key can not be found (perhaps due to a typo)
3. The token secret does not match the key
4. The token has been revoked
5. The token has expired

A token that authenticates but lacks the scope an API call needs gets an [HTTP 403: Forbidden](@/docs/api/legacy/errors/403-forbidden/index.md) response instead. See [scopes](@/docs/account/api-tokens/index.md#scopes).

If you are having trouble authenticating your requests to the API, please reach out to support@bonsai.io.