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

# Authentication and scopes

> Use bearer API keys and least-privilege scopes securely.

The Brightalk REST API authenticates server-to-server requests with bearer API keys. The key determines the organization and the operations the request may perform.

## Send a bearer key

Send the key in the `Authorization` header on every request. The syntax is exact: `Bearer`, one space, then the key.

```http theme={null}
Authorization: Bearer $BRIGHTALK_API_KEY
```

A missing or malformed bearer header returns `401 authentication_required`. A syntactically valid key that is unknown or revoked returns `401 invalid_api_key`.

## Create and store keys

Create a `bt_live_` key in [Brightalk API settings](https://www.brightalk.ai/settings/integrations/api). The complete secret is displayed once. Copy it directly into a server-side secret manager, never source control, logs, browser storage, mobile code, or client-delivered environment variables.

Choose an expiry when appropriate. A key past its expiry returns `401 api_key_expired`. Revocation takes effect for subsequent requests and is the right response to suspected exposure or completed temporary testing.

## Select least-privilege scopes

Scopes are checked for each operation and are deny-by-default. A write or run scope does not include its matching read scope, and a read scope does not include write access.

| Resource                      | Read scope                         | Write or run scope |
| ----------------------------- | ---------------------------------- | ------------------ |
| Agent catalog (`GET /agents`) | `calls:read` **or** `batches:read` | —                  |
| Contacts                      | `contacts:read`                    | `contacts:write`   |
| Calls                         | `calls:read`                       | `calls:write`      |
| Batches                       | `batches:read`                     | `batches:write`    |
| Automations                   | `automations:read`                 | `automations:run`  |

`GET /agents` is the catalog exception: either `calls:read` or `batches:read` authorizes it (`anyOf`). Select both members of a resource pair only when a server must create or start work and then retrieve it. The pairing is a usability recommendation, not an implication between scopes.

## Rotate and revoke safely

Create a replacement key with the minimum required scopes, update the server-side secret, verify requests with the replacement, and then revoke the old key. Do not expose either secret during overlap. Rotation does not change resource ownership or bypass existing idempotency claims.

## Use the GET playground carefully

<Warning>
  A key entered in an interactive GET playground traverses Mintlify's proxy. Use a temporary, least-privilege read key, avoid write/run scopes, and revoke the key immediately after testing.
</Warning>

Mutation endpoints provide copyable samples without an interactive mutation control. For normal integrations, send all requests directly from your server to `https://api.brightalk.ai`.