Workspaces and API keys
Every resource in the API — channels, contacts, messages, campaigns, balance — lives inside a workspace. A workspace is the primary isolation boundary: data from one workspace is never visible to another.
API keys are workspace-scoped. A key can only access resources belonging to the workspace it was created in.
| Concept | Description |
|---|
| Workspace | The billing and operational container. Owns channels, contacts, balance, and API keys. |
| User | A person with dashboard access. Can be a member of one or more workspaces. |
| API key | A long-lived bearer token scoped to one workspace. Used for all /v1 API calls. |
Scheme
All /v1 routes expect:
Authorization: Bearer <api_key>
| Aspect | Detail |
|---|
| Scheme | Bearer — not a user session token. |
| Key scope | Workspace-scoped. Rate limits and policies apply per key. |
| Management | Create, label, and revoke keys in the dashboard under Workspace settings. |
What the server derives
From a valid key the gateway resolves:
- Workspace for tenancy, balance, and policy.
- Rate limit bucket for the key.
- Access scope for management routes (webhooks, billing writes) when applicable.
Best practices
- Storage — Keep keys in a secrets manager or environment variables; never commit them or expose them in browsers.
- Rotation — Rotate on a schedule or after incidents and role changes.
- Environments — Prefer separate keys for staging and production to limit blast radius.
Errors
| Status | Meaning |
|---|
| 401 | Missing or invalid token |
| 403 | Valid token but insufficient permission for the route |
401 / 403 — response fields
Machine-readable error code. See Errors for the full list. Human-readable detail safe to log (avoid echoing secrets).
