# Authentication

Every API request authenticates with an API key passed as a bearer token in the `Authorization` header:

```bash
curl https://us1.platform.bird.com/v1/email/messages \
  -H "Authorization: Bearer bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ..."
```

Keys are workspace-scoped: a key authenticates as its workspace, carries the scopes chosen at creation, and cannot reach resources in any other workspace. How to create, scope, rotate, and revoke keys is covered in the [Authentication & API keys guide](/docs/guides/authentication) (keys live under [**Developers → API keys**](https://bird.com/dashboard/w/api-keys)); this page covers the wire-level contract.

## Key format

```text
bk_us1_Ab3xKq9mP2wR5tY8uI1oL4nJ...
└┬┘└┬┘ └──────────┬──────────┘└┬┘
 │  │          payload      checksum
 │  └ region (routes the request)
 └ Bird key prefix
```

A key is `bk_{region}_{payload}{checksum}`:

- **`bk_{region}_`** — the prefix identifies the credential type and the region the key was created in. `bk_us1_` keys are valid only against `https://us1.platform.bird.com`, `bk_eu1_` keys only against `https://eu1.platform.bird.com` — the prefix is what official SDKs and the CLI use to pick the host. The fixed `bk_` prefix is registered with GitHub secret scanning, so a Bird key leaked in a public repository is detected and reported.
- **Payload** — a long random string with 128+ bits of entropy.
- **Checksum** — the final 6 characters are a checksum of the rest of the key, letting a client reject a mistyped or truncated key locally before any request is made.

The full key is returned exactly once, in the response that creates it. Bird stores only an HMAC-SHA-256 hash — the plaintext cannot be retrieved again, and the dashboard shows only a short `key_prefix` (the first 12 characters). A lost key is revoked and replaced, never recovered.

## Failure responses

All failures use the standard [error envelope](/docs/api/errors).

| Status | When                                                                                                          |
| ------ | ------------------------------------------------------------------------------------------------------------- |
| `401`  | The `Authorization` header is missing, the key is malformed or unknown, or the key has been revoked.          |
| `403`  | The key is valid but lacks the scope the endpoint requires.                                                   |
| `421`  | The key's region does not match the host — a `bk_eu1_...` key sent to `us1.platform.bird.com`, or vice versa. |

The `421 Misdirected Request` body (error type `misdirected_error`, code `E01010`) names the correct regional host, so a client can detect the mistake and re-send without guesswork. See [Base URLs & regions](/docs/api/regions).

## Dashboard sessions are not API keys

The Bird dashboard does not use API keys: a person logging in gets a session cookie, scoped to their own user permissions. Session cookies are not accepted on the programmatic API surface, and API keys are not accepted by the dashboard. Server workloads always use API keys.

## Related

- [Authentication & API keys guide](/docs/guides/authentication) — creating, scoping, rotating, and revoking keys
- [Base URLs & regions](/docs/api/regions) — regional hosts and the region model
- [Errors](/docs/api/errors) — the error envelope and catalog