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.
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. 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.
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.
calls:read covers call metadata and summaries, but it does not authorize full transcript content. Grant transcripts:read explicitly before calling GET /calls/{call_id}/transcript; existing keys do not gain that scope automatically. recordings:read follows the same rule: it is also independent of calls:read, and existing keys do not gain it automatically.
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.
This is also the only way to add a scope to an integration that is already live. PATCH on an API key updates only its name; there is no endpoint that changes an existing key’s permissions. To start using recordings:read (or any scope not already on your key), create a new key with the full scope set you need, including the new one, and rotate to it with the same steps above.
Use the GET playground carefully
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.
https://api.brightalk.ai. 
