API reference
Authentication
API keys, the Bearer scheme, and scopes.
Every /v1 request authenticates with an API key sent as a Bearer token:
Authorization: Bearer sk_live_...Keys are issued per organization and stored only as a hash — the plaintext is shown once at creation. Every request is scoped to the key's org; an id from another org is invisible, so you cannot read or write across tenants.
Scopes
A key carries a fixed set of scopes. A request to a route whose required scope the key lacks
is rejected with 403.
| Scope | Grants |
|---|---|
approvals:write | create approvals (POST /v1/approvals) |
approvals:decide | decide approvals (POST /v1/approvals/:id/decision) |
approvals:read | read approvals (GET /v1/approvals/:id) |
audit:read | export the audit log (GET /v1/audit) |
webhooks:write | manage webhook endpoints |
webhooks:read | read webhook endpoints |
billing:manage | manage the org's billing |
Errors
Auth and validation failures return a JSON DomainError:
{ "error": { "code": "forbidden", "message": "Missing required scope: approvals:write" } }| Status | Meaning |
|---|---|
401 | missing or invalid key |
403 | valid key, but it lacks the required scope |
402 | free-tier limit reached — upgrade to continue |
422 | request body failed validation |