> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brudcast.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Authentication

> API keys for the platform API, sending keys for the email send API and SMTP users for the relay: which works where and how to send it.

Brudcast uses three credentials, one per integration surface. Each belongs to a single organization,
so the credential alone decides which organization a request acts on.

## Which credential works where

| Credential  | Looks like                                                                            | Create it in                                           | Works on                                                                              | Send it as                                                  |
| ----------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| API key     | `bk_live_` followed by 64 hex characters                                              | **Developers > API Keys**                              | The platform API. Also the email send API, if it has the **Send Messages** permission | `X-API-Key: bk_live_…` or `Authorization: Bearer bk_live_…` |
| Sending key | `bk_live_` followed by 64 hex characters                                              | **Channels > Email**, domain, **Sending Keys** tab     | The email send API, from its own domain only                                          | `Authorization: Bearer …`                                   |
| SMTP user   | A generated username such as `a1b2c3d4@mail.example.com`, and a 32-character password | **Channels > Email**, domain, **SMTP Credentials** tab | The SMTP relay, from its own domain only                                              | SMTP `AUTH PLAIN` or `AUTH LOGIN`, after TLS                |

Every secret is shown once, when it's created or regenerated. Brudcast stores only a hash of API
keys and sending keys, so a lost key can't be recovered. Regenerate it instead.

## Platform API keys

<Snippet file="auth-headers.mdx" />

A few rules follow from how keys are checked:

* **Bearer only works with the prefix.** Brudcast reads `Authorization: Bearer` as an API key only
  when the value starts with `bk_`.
* **The organization comes from the key.** You don't need `X-Organization-Id`. If you send it and
  it names a different organization, the request fails with `403` and
  `This API key cannot act on the requested organization`.
* **Scopes narrow what the key can reach.** A request to an endpoint the key has no scope for fails
  with `403` and code `E_INSUFFICIENT_SCOPE`. See [API keys](/developers/api-keys#scopes).
* **Some endpoints never accept a key.** Key management, SMTP users, sending keys, billing,
  subscriptions, the wallet, invoices and notifications are dashboard-only. They answer `403` with
  `This endpoint cannot be accessed with an API key`. A leaked key can't create more credentials or
  move money.
* **A key acts for the member who created it.** If that member leaves the organization, their keys
  are revoked. If their account is suspended, the keys stop working.

Every authentication failure returns the same response, whatever the cause: an unknown, revoked or
expired key, or a request from an IP address that isn't on the key's allowlist. This is deliberate,
so a caller probing with stolen or guessed keys learns nothing.

```json theme={"system"}
{
  "success": false,
  "message": "Unauthorized access",
  "code": "E_UNAUTHORIZED_ACCESS"
}
```

If you get this with a key you believe is valid, check its status and IP allowlist in
**Developers > API Keys**.

## Sending keys

The email send API accepts only `Authorization: Bearer <key>`. It ignores `X-API-Key`.

Two kinds of key work there:

| Kind               | How you get it                                                                              | Can send from                                                                     |
| ------------------ | ------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| Domain sending key | **Add Sending Key** on the domain's **Sending Keys** tab                                    | Only that domain. Its permission is fixed at `messages:send` and can't be changed |
| Organization key   | An API key created with **Messages** set to **Full access**, which includes `messages:send` | Any sending domain your organization owns                                         |

Prefer domain sending keys for applications that send from one domain. A leaked domain key can
only send from that domain and can't read anything.

A key goes through these statuses on its way to the send API:

| Status                | Meaning                                                                |
| --------------------- | ---------------------------------------------------------------------- |
| `provisioning`        | Just created or regenerated. The send API doesn't accept it yet        |
| `active`              | Ready to send                                                          |
| `provisioning_failed` | The send API never received it. Regenerate the key or create a new one |

<Note>
  You can't add the **Send Messages** permission to an existing API key. Create a new key with it.
  This is because the send API can only receive a key while its secret still exists, which is at
  creation or regeneration.
</Note>

The **Brudcast trial address** has no sending keys and no SMTP credentials. Add and verify your own
domain before you use the send API or SMTP. See [Email overview](/channels/email/overview).

## SMTP users

An SMTP user is a username and password for the relay, tied to one sending domain.

* Brudcast generates both. The username looks like an address on your domain, for example
  `a1b2c3d4@mail.example.com`. The password is 32 characters and shown once.
* Authenticate with `AUTH PLAIN` or `AUTH LOGIN`. On ports `587`, `2525` and `25`, run `STARTTLS`
  first. Port `465` is TLS from the start.
* The envelope sender (`MAIL FROM`) must be on the SMTP user's domain.
* You can regenerate the password or deactivate the user. After a regenerate, the old password can
  keep working for a few minutes.

See [SMTP relay](/developers/sending/smtp-relay) for connection settings and
[SMTP users](/channels/email/smtp-users) for managing them.

## Keeping credentials safe

* Call Brudcast from your server. Never put a key in browser or mobile app code.
* Use one key per application or environment, so you can revoke one without breaking the rest.
* Give each API key only the scopes it needs.
* Add an IP allowlist to keys used from fixed servers.
* Set an expiry on keys that are only needed for a while.
* If a key leaks, revoke it in the dashboard. It stops working on the next request.

<Columns cols={2}>
  <Card title="API keys" icon="key-round" href="/developers/api-keys">
    Create keys, choose scopes and read request logs.
  </Card>

  <Card title="Errors" icon="circle-alert" href="/developers/errors">
    Every error shape and what to do about it.
  </Card>
</Columns>