Authentication
API keys, permissions, workspace binding, test keys, and how to handle a leak.
Keys
Every request authenticates with a bearer token:
Authorization: Bearer brk_your_api_keyTwo kinds:
| Prefix | Behavior |
|---|---|
brk_live_ | Real sends, real data |
brk_test_ | Simulator: identical validation and response shapes, zero real sends, "sandbox": true on every response |
A shared public sandbox key is printed in the quickstart so you can evaluate the full surface before you have an account.
Keys are created in the dashboard, and the full value is shown once at creation. During onboarding we mint yours with you.
Permissions
Each key carries one permission level; every endpoint documents the minimum it needs.
| Level | Grants |
|---|---|
read | Contacts, capability, usage, opt-out reads |
write | Everything read does, plus sends, signals, conversation reads, opt-out and assistant writes |
admin | Everything, plus key management surfaces |
Conversation history requires write rather than read deliberately: message content is the most sensitive thing in the account, and a read-only key that can dump every thread is not read-only in any way that matters.
Workspace binding
Every key is bound to one workspace, and the boundary is enforced identically across REST, MCP, sends, reads, capability checks and usage reporting. A key cannot see or touch lines, contacts or conversations outside its workspace. Give staging a key bound to a staging workspace and it physically cannot reach the lines your customers know.
Handling keys
- Server-side only. A key in browser or mobile code is public.
- One key per integration, named for it, so a leak has a blast radius of one revoke.
- Revoke instantly in the dashboard; a revoked key fails with
401 invalid_api_keyon the next request. - Never commit keys. Environment variables or a secret manager.
Test-first setup
Build against a brk_test_ key: every messaging endpoint, the status timers, and the MCP tools all behave realistically with zero risk. Swap in the live key at go-live and change nothing else. Contacts and capability lookups answer from the simulator as well, and a test key is bound to no workspace, which is the guarantee that a sandbox integration can never touch production data by accident.