Skip to content

Authentication

Authenticate every request with an API key sent as a Bearer token.

API keys

Create keys in Developers → API keys (keys can only be created from the dashboard, not with another key). Each key belongs to one organization and carries its own set of permissions — never more than the person who created it holds. The full secret is displayed once; Engage stores only a keyed hash and afterwards shows the prefix so you can recognise the key.

curl https://engage.swastik.ai/v1/numbers \
  -H "Authorization: Bearer egk_live_xxxxxxxxxxxxxxxx"

An organization can have up to 50 active keys.

Key prefixes

When you create a key you choose a label of live or test, which becomes its prefix (egk_live_… or egk_test_…).

Test keys are not a sandbox
Both kinds of key behave the same and send real WhatsApp messages through your connected numbers. Use the label to tell keys apart (for example, the key your staging server uses), and test against your own phone number.

Permissions

Grant each key only what it needs. These are the permissions a key can hold:

PermissionAllows
messages:sendSend messages (single and bulk), read a message, list numbers and templates
numbers:readRead connected numbers, business profiles and QR codes
templates:readList and read templates and media
templates:writeCreate, edit, delete, sync templates; upload template samples
contacts:readRead contacts, tags, lists, segments and attributes
contacts:writeCreate and update contacts, tags, lists, segments and attributes
contacts:importStart CSV imports
contacts:exportDownload the CSV export
inbox:read_allList conversations and read their messages and notes
inbox:replyReply in conversations, change status, add notes, manage canned responses
inbox:assignAssign conversations
campaigns:readList campaigns, read reports, estimate audiences
campaigns:writeCreate, edit, duplicate and delete campaigns
campaigns:launchLaunch, pause, resume and cancel campaigns
media:writeUpload, list and delete media
automations:readRead automations and their runs
automations:writeCreate and edit automations; post automation events
analytics:readRead analytics
developers:manageManage webhook endpoints and list or revoke API keys

Keys can also hold flows:* and catalog:* for WhatsApp Flows and commerce features. A request without the required permission returns 403 forbidden. Some actions — deleting contacts, managing numbers, team members and billing — can only be done by signed-in people in the dashboard.

IP allowlist

Optionally restrict a key to specific IPv4/IPv6 addresses or CIDR ranges, e.g. 203.0.113.0/24. Requests from other addresses are rejected with 403 forbidden.

Expiry and revocation

Keys can carry an expiry date at least one hour in the future; expired keys return 401. Revoking a key in the dashboard takes effect immediately. The dashboard also shows when and from where each key was last used.

Failed authentication

401 Unauthorized
{
  "error": {
    "code": "unauthorized",
    "message": "authentication required",
    "details": {},
    "request_id": "01a1cc77ecf374f9bdd7cf0b762e870d"
  }
}
Rotate leaked keys immediately
If a key is exposed, create a replacement, deploy it, then revoke the old key. Revocation cannot be undone.
Something unclear or missing on this page? Tell us at contact@swastik.ai