Authentication
Every request carries an API key. Each key has permissions, so a key can only do what you chose for it.
Send the key as a bearer token
Header
Authorization: Bearer wak_...You can send the key in an X-API-Key header instead. Use whichever your tools prefer. Requests must use https.
- Keep keys on your server, in an environment variable such as
EZREACH_API_KEY. A key in a web page or a mobile app is visible to everybody who opens it. - A missing, malformed or revoked key gets
401 UNAUTHORIZED. - If the person who made a key is removed from your team, their keys stop working. Make keys under an account that stays.
- Use one key for each system, so you can revoke one without touching the others. You see the last time and the network address each key was used from in Settings > API keys. We keep that address for security.
Permissions
You choose a key's permissions when you create it. They cannot be changed later: make a new key instead. A key that lacks the permission an endpoint needs gets 403 MISSING_SCOPE, and the answer names the permission it needed.
| Permission | What it allows | Endpoints |
|---|---|---|
account:read | Read account. GET /account: the workspace, its WhatsApp numbers and this key. | GET /account |
contacts:read | Read contacts. List and look up contacts. | GET /contactsGET /contacts/{phone} |
contacts:write | Write contacts. Create, update, bulk upsert and delete contacts. | POST /contactsPOST /contacts/bulkPATCH /contacts/{phone}DELETE /contacts/{phone} |
messages:read | Read WhatsApp messages. The status of a WhatsApp message. | GET /messages/{id} |
messages:send | Send WhatsApp messages. Send template, text and media messages. | POST /messages |
templates:read | Read templates. List WhatsApp message templates. | GET /templates |
events:read | Read bookings. Look up a booking's journey steps. | GET /events/{key} |
events:write | Report events. Report, cancel and move bookings (journeys). | POST /eventsPOST /events/cancelPOST /events/reschedule |
email:read | Read emails. The status of an email sent through the API. | GET /email/messages/{id} |
email:send | Send emails. Send one email per request from your verified From addresses. | POST /email/messages |
email:consent | Record email consent. Record who agreed to receive email and who asked to stop. | POST /email/consent |
Presets
The key form offers these shortcuts. Choose Custom to pick permissions one by one.
| Preset | What it means | Permissions |
|---|---|---|
| Full access | Everything the API can do, including permissions added later. | All of them, including any added later |
| Read only | Reads only: account, contacts, templates, bookings and message and email status. Sends and changes nothing. | account:readcontacts:readmessages:readtemplates:readevents:reademail:read |
| Send messages | Sends WhatsApp messages and emails and reads their status and your templates. Cannot change contacts. | account:readtemplates:readmessages:sendmessages:reademail:sendemail:read |
When a permission is missing
403 Forbidden
{
"error": {
"message": "This API key does not have the permission \"email:send\" (send emails). Give the key this permission or use another key: Settings > API keys.",
"code": "MISSING_SCOPE",
"details": {
"required": "email:send",
"granted": [
"account:read",
"contacts:read"
]
}
}
}
