Authentication and scopes
API keys, OAuth access tokens, the three scopes and what each one allows.
Every request to /v1 carries a bearer token:
Authorization: Bearer gp_live_xxxxxxxxxxxxxxxxTwo kinds of token exist.
| Token | Looks like | For | Obtained |
|---|---|---|---|
| API key | gp_live_… | Your own account, Make, n8n, scripts, a local MCP | Settings, Integrations |
| OAuth access token | gp_at_… | A platform acting for its users | Connect OAuth |
Both resolve to one project (one WhatsApp number) and a list of scopes. Every call runs with the same rights as the owner of the project in the app: a key can never read or write beyond what its owner sees.
Scopes
| Scope | Allows |
|---|---|
read | Everything under GET: project, events, occurrences, communities, sequences, planned sends, deliveries, broadcasts, notifications |
write | Configure: create and update events, pause and resume, sequences and messages, sync, resync, media uploads, webhooks, member webhook, backup admin |
send | Send now: one-off messages, edit, cancel and retry a planned send, broadcasts |
send is separate from write on purpose: a send consumes the reputation of your customer's WhatsApp number. Give a partner platform read and write, keep send for tools you trust.
Errors
| HTTP | Code | Meaning |
|---|---|---|
| 401 | unauthorized | Missing token |
| 401 | invalid_api_key | Invalid, malformed, revoked or expired token |
| 403 | api_not_enabled | The API is not enabled on this project |
| 403 | insufficient_scope | The token lacks the scope of this endpoint. The message names it. |
Good habits
- One key per integration, named after it. Revoke the one you stop using.
- Never put a key in a URL, a log or a client-side app. Server to server only.
- Rotate a key by creating a new one, switching, then revoking the old one. A revoked key stops working within a minute.
Idempotency-Keyis scoped to the caller: the API key, or the grant for an OAuth token.- Keys are stored hashed. If you lose one, create another: nobody can show it to you again.