Authentication
The credential types — workspace bk_ keys, CRM crk_ Connections keys, agent signing secrets, webhook secrets — what each can do, and how to keep them safe.
View as MarkdownAll API requests authenticate with a Bearer token. Which token depends on what you're doing:
| Credential | Where to get it | Scope |
|---|---|---|
Workspace API key (bk_…) | Settings → API keys | Full workspace access: the MCP server, Contacts API, and workspace endpoints. Equivalent to the owner — guard it accordingly. |
CRM Connections key (crk_…) | CRM → Connections | Write-only lead ingest into one board + column. The key you can hand to a partner site. |
| Agent signing secret | Chat service → Embed → Identity verification | Server-side HMAC signing for verified identity. Never sent as a header; never shipped to a browser. |
| Webhook signing secret | Settings → Integrations → Webhooks | Lets you verify webhook deliveries came from OpenAgent. |
Using a key
curl https://app.openagent.work/... \ -H "Authorization: Bearer bk_your_key"
Errors
| Status | Meaning |
|---|---|
401 | Missing or invalid key. |
403 | Valid key, but the action isn't allowed — including upgrade_required when a plan entitlement is missing. |
422 | The request was understood but the payload is invalid — the body says which field. |
429 | Rate limited — back off and retry. |
Rotate on suspicion
Keys are shown once at creation. If one may have leaked, delete it in Settings (bk_) or the Connections tab (crk_) — revocation is immediate — and issue a fresh one.