Authentication & keys
Every request carries a secret API key in the Authorization header:
curl https://api.saei.automize.sa/v1/me -H "Authorization: Bearer sk_live_..."X-Api-Key: sk_live_... works too, for tools that cannot set Authorization. Requests go over HTTPS only.
Live and test keys#
| Key | Starts with | What it does |
|---|---|---|
| Test | sk_test_ | Everything is simulated. Messages never reach WhatsApp, nothing is billed, and only test-mode webhook endpoints receive events. |
| Live | sk_live_ | Real messages to real customers through your connected numbers. |
The mode belongs to the key, not to the request, so the same code runs in both: swap the key to go live. Objects never cross modes: a test key cannot read a live message, and a live key cannot read a test one.
Scopes#
A key can do only what its scopes allow. Each endpoint in the reference names the scope it needs; without it the API answers 403 insufficient_scope and tells you which scope is missing in required_scope.
| Scope | Allows |
|---|---|
messages:send | Send messages; use the test-mode helpers |
messages:read | Read messages and their status |
webhooks:read / webhooks:write | See / manage webhook endpoints and deliveries |
templates:read | Read templates (coming soon) |
contacts:read / contacts:write | Read / manage contacts (coming soon) |
When you create a key you can pick a preset (Full access, Messaging, Read only) or choose scopes one by one. Give each integration the smallest set it needs.
Keeping keys safe#
- The full key is shown once, when it is created. We store only a hash of it.
- Keep keys in environment variables or a secrets manager, never in client-side code, a mobile app or a repository.
- Create one key per integration so you can revoke one without breaking the others.
- Revoke a key the moment you suspect it leaked: Developers → API keys → Revoke. It stops working immediately (
api_key_revoked). - Keys can only be created in the portal, never through the API, so a leaked key cannot mint more keys.
Plans#
Test keys work on every plan. Live API access is part of the plans that include it; if yours does not, live requests answer api_access_not_in_plan.