Authentication
One bearer key per integration, scoped to what it may do.
Every request carries a key:
Authorization: Bearer sk_live_...Keys in the query string or the request body are refused. A URL is logged by every proxy it passes through, and that is how customer keys leak.
Keys are shown once
We store a hash, not the key. The plaintext exists only in the response that creates it — copy it then. If you lose it, revoke it and issue another; there is no way to read it back.
You can hold several keys at once and revoke them one at a time, which is what makes rotation possible without downtime: issue the new one, move your traffic, revoke the old one.
Scopes
A key carries scopes, fixed at creation. A call outside them answers 403 with
insufficient_scope and names the scope it wanted.
| Scope | Grants |
|---|---|
account:read | Read your plan, credits and rate limit. |
automation:read | Read workflows and their executions. |
automation:write | Trigger a workflow. |
campaigns:read | Read campaigns and their dispatches. |
campaigns:write | Create, change, start, pause, resume, cancel and delete campaigns. |
contacts:read | Read contacts and the attributes defined on them. |
contacts:write | Create, change, bulk-import and delete contacts. |
gateways:read | Read the gateways your messages can leave through. |
groups:read | Read contact groups. |
groups:write | Create and change groups, and move contacts in and out. |
inbox:read | Read conversations and their messages. |
inbox:write | Mark a conversation read, and reply to it. |
messages:read | Read messages you have sent. |
messages:write | Send, cancel and resend messages. |
templates:read | Read message templates. |
templates:write | Create, change and delete templates. |
webhooks:read | Read webhook endpoints and their delivery history. |
webhooks:write | Create, change and delete webhook endpoints. |
Give a key the least it needs. A key that only reports delivery status wants
messages:read and nothing else — if it leaks, it cannot send.
Admin keys
Keys belonging to an instance administrator answer GET /account with
type: "admin", and plan, credits and usage come back null rather than
missing. A shape that disappears forces you to guess; a shape that is null can
be checked.