Authentication and API keys
Every request carries an API key as a bearer token. A key belongs to one organization, may be bound to one workspace, and holds a set of scopes that decide which operations it can call.
Key types
| Prefix | Use |
|---|---|
ba_live_ | Production traffic. |
ba_test_ | Same access as a live key; its requests are recorded as test traffic. |
Keys are shown once, when they are created. BidAuthor stores only a hash; a lost key is revoked and replaced, never recovered.
Scopes
A key holds one or more scopes. An operation that needs a scope the key lacks fails with 403 api_scope_missing, before anything runs or is charged. GET /api-keys/scopes lists every scope a key can carry.
| Group | Scopes |
|---|---|
| Documents | documents:read, documents:write, documents:delete |
| Proposals | rfp:read, rfp:write, rfp:generate, rfp:finalize |
| Arthur | agent:invoke, agent:read |
| Categories | categories:read, categories:write, categories:delete |
| Workspaces | workspaces:read, workspaces:write, workspaces:delete |
| Webhooks | webhooks:read, webhooks:write |
| Runs | runs:read, runs:write |
| Suggestions | suggestions:read, suggestions:write |
| Notifications | notifications:read, notifications:write, devices:write |
| Account | keys:read, keys:write, organizations:admin |
| Billing | billing:read, billing:write |
Organization and workspace
The key's organization is fixed; X-Organization-ID is not needed. Workspace resolution follows the key:
- A key bound to a workspace reads and writes there, whatever headers are sent.
- An organization-wide key reads from the default workspace unless
X-Workspace-IDnames another, and must sendX-Workspace-IDon everyPOST,PUT,PATCHandDELETE. Without it the request fails with400 workspace_id_required, so a write never lands in the default workspace by accident.
Creating more keys
A key holding keys:write can mint further keys for its organization, when the organization has programmatic keys enabled. A new key's scopes must be a subset of the parent's and cannot include keys:write. Plan limits on the number of keys and scopes per key apply.
The response includes secret once. GET /api-keys lists the organization's keys without secrets, and POST /api-keys/{key_id}/revoke revokes one; revoking an already revoked key returns it unchanged.
Failures
| Code | Status | Meaning |
|---|---|---|
api_key_invalid | 401 | The key is unknown, malformed, or a key type this API does not accept. |
api_key_revoked | 401 | The key was revoked. |
api_key_expired | 401 | The key passed its expiry date. |
api_scope_missing | 403 | The key lacks a scope the operation needs. |
workspace_id_required | 400 | An organization-wide key wrote without X-Workspace-ID. |
See Errors for the envelope and the full list.