Use this matrix when creating API keys with least privilege.
Auth model
Authenticated endpoints accept:
X-Api-Key(recommended for server integrations)- Bearer session token (dashboard / user sessions)
Permissions use resource actions (for example messages:send).
API key scopes intersect the creator’s current workspace role: both must allow
the operation. Scopes match exactly; contacts:write does not imply
contacts:read. An explicit *, or an empty scope list on a legacy key,
preserves role-limited access. Prefer explicit scopes for new integrations.
Operations without a declared REST scope reject narrowly scoped keys. Unknown scope names do not grant access. Some account/settings operations have not yet been assigned a narrow scope; use the dashboard for those operations.
OAuth access tokens have separate authorization and workspace grants. They are
not API keys. MCP scopes such as mcp:read do not grant REST permissions to an
API key: keys used by MCP tools that call REST also need the corresponding
resource scopes. OAuth tokens retain the OAuth/MCP scope policy.
Integrator-focused permissions
| Domain | Example paths | Typical permissions |
|---|---|---|
| Messages | /v1/messages* |
messages:send, messages:read |
| Channels | /v1/channels* |
channels:read, channels:write |
| Contacts | /v1/contacts* |
contacts:read, contacts:write |
| Templates | /v1/templates* |
templates:read, templates:write |
| Media | /v1/media/*, /v1/messages/uploads/* |
messages:send |
| Developer webhooks | /v1/settings/developer/webhooks* |
org settings access (configure in app) |
| WABA | /v1/waba* |
waba:read, waba:write |
| API keys | /v1/api-keys* |
api_keys:read, api_keys:write |
Roles (app)
- Member — day-to-day messaging and contacts.
- Admin — member + API keys, invitations, destructive ops.
- Owner — admin + organization-level actions.