Docs

Authentication

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

API keys

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

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

Live and test keys

Prefix	Mode	Behaviour
`egk_live_`	Live	Sends real WhatsApp messages through your connected numbers.
`egk_test_`	Test	Validates requests against the same rules without contacting Meta; simulated status webhooks are emitted.

Permissions

Grant each key only what it needs. Common permissions:

Permission	Allows
`messages:send`	Send messages and read message status
`templates:read`	List and read templates
`templates:write`	Create, edit and delete templates
`contacts:read`	List and read contacts, tags, lists
`contacts:write`	Create and update contacts, tags and lists
`campaigns:write`	Create campaigns
`campaigns:launch`	Launch, pause, resume and cancel campaigns
`analytics:read`	Read analytics

A request without the required permission returns 403 forbidden.

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.

Expiry and revocation

Keys can carry an expiry date. Revoking a key in the dashboard takes effect immediately. The dashboard also shows when 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.