Browse the docs

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.

PermissionWhat it allowsEndpoints
account:readRead account. GET /account: the workspace, its WhatsApp numbers and this key.GET /account
contacts:readRead contacts. List and look up contacts.GET /contactsGET /contacts/{phone}
contacts:writeWrite contacts. Create, update, bulk upsert and delete contacts.POST /contactsPOST /contacts/bulkPATCH /contacts/{phone}DELETE /contacts/{phone}
messages:readRead WhatsApp messages. The status of a WhatsApp message.GET /messages/{id}
messages:sendSend WhatsApp messages. Send template, text and media messages.POST /messages
templates:readRead templates. List WhatsApp message templates.GET /templates
events:readRead bookings. Look up a booking's journey steps.GET /events/{key}
events:writeReport events. Report, cancel and move bookings (journeys).POST /eventsPOST /events/cancelPOST /events/reschedule
email:readRead emails. The status of an email sent through the API.GET /email/messages/{id}
email:sendSend emails. Send one email per request from your verified From addresses.POST /email/messages
email:consentRecord 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.

PresetWhat it meansPermissions
Full accessEverything the API can do, including permissions added later.All of them, including any added later
Read onlyReads only: account, contacts, templates, bookings and message and email status. Sends and changes nothing.account:readcontacts:readmessages:readtemplates:readevents:reademail:read
Send messagesSends 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"
      ]
    }
  }
}