API keys & scopes

Four key tiers. Pick the narrowest one that fits the job.

Prefix	Scope	Use it for
sa_	Super admin	Platform operator only. Creates and deletes tenants.
tk_	Tenant master	Every workspace, inbox, domain, and webhook in your tenant. The key you log into the dashboard with.
wk_	Workspace master	One workspace only. Hand these to reseller customers so they can manage their own inboxes without seeing anyone else's.
ak_	Inbox scoped	A single inbox — its messages, drafts, threads, lists. Give this to the agent runtime.

Least privilege

If the agent only needs to read its own inbox and send from it, give it an ak_ key. A tk_ key leaking exposes every workspace in your tenant; an ak_ key leaking only exposes one inbox. Rotate compromised keys by deleting and recreating the inbox (or, for workspace keys, via DELETE /v1/workspaces/{id}/keys/{key_id}).

Passing the key

Two headers work:

X-API-Key: tk_...
# or
Authorization: Bearer tk_...

WebSocket connections accept the ?api_key= query parameter too, for browser clients that can't set headers on new WebSocket.