API keys and sender assignment
Create API clients, rotate keys, revoke access, and restrict keys to selected senders.
Lifecycle
Create one API client per integration or application area. For example, use one `otp` client for login verification and one `send_message` client for transactional notifications.
Free Sandbox keys use managed routing and do not need a customer sender assignment. Paid connected-sender keys should be assigned only to the numbers that integration needs.
API keys are write-only secrets. The raw key is returned once on create or rotation; after that the platform stores only the hash.
- Create: returns `api_key` once.
- Rotate: returns a new `api_key` once.
- Revoke: disables a client without deleting history.
- Sender mode: managed routing omits `sender_id`; connected mode uses an explicitly assigned number.
- Delete: removes the dashboard record only when the workspace intentionally removes the client.
- Format: customer API keys are generated with the `was_` prefix.
Dashboard workflow
Create and manage API clients from Dashboard > API Keys. The dashboard returns the key once on create or rotation, then stores only the hashed credential.
For Free Sandbox, leave the sender empty. For paid connected-sender mode, assign only the numbers that the integration needs.
- Create key: choose a name and role, then copy the key immediately.
- Free Sandboxcreate the correct role and leave sender assignment empty.
- Paid modeselect the connected numbers this key may use.
- Rotate key: update the backend environment variable and redeploy before deleting the old value from secret storage.
- Revoke key: stops future API requests while keeping historical message records.
- Lost key: rotate the client, copy the new key, update your backend secret, redeploy, then verify `GET /api/senders`.
Key visibility
The raw API key is only shown when created or rotated. Store it in a server-side secret manager or environment variable.
Customer management routes
These routes are used by the customer dashboard with an authenticated customer session. They are documented here so backend developers understand where API keys come from, but normal server integrations should not call them with `x-api-key`.
If you automate workspace administration, keep that automation server-side and verify it is allowed to act for the current workspace before changing API clients or sender assignments.
/api/customer/api-clientsList API clients for the current customer workspace.
/api/customer/api-clientsCreate an API client and return the raw `api_key` once.
| Parameter | Type | Description |
|---|---|---|
namerequired | string | Display name, 1 to 120 characters. |
role | send_message | otp | Integration role. Defaults to `send_message`. |
sender_ids | uuid[] | Connected sender IDs to assign, max 100. |
metadata | object | Optional integration metadata. |
/api/customer/api-clients/{client_id}Update name, role, or metadata for an API client.
/api/customer/api-clients/{client_id}/rotate-keyGenerate a new raw `api_key` once and replace the stored key hash.
/api/customer/api-clients/{client_id}/revokeRevoke an API client so future integration requests fail.
/api/customer/api-clients/{client_id}/sendersReplace sender assignments for the API client.
| Parameter | Type | Description |
|---|---|---|
sender_idsrequired | uuid[] | Unique sender IDs, max 100. |
Verify assigned senders
This verification is for paid connected-sender mode. Call `GET /api/senders` with the key and confirm the intended number is returned as active and connected.
In managed Free Sandbox, an empty customer sender list is expected. Test the send endpoint without `sender_id` instead.
/api/sendersReturn senders visible to this API key.
| Parameter | Type | Description |
|---|---|---|
x-api-keyrequired | header | Customer API key created in the dashboard. |
[
{
"sender_id": "9f4b5d4c-0000-4000-9000-123456789abc",
"display_name": "Main support",
"phone_number": "212612345678",
"status": "connected",
"is_active": true
}
]Need help?
Use Book Integration Help if you want setup help for OTP or automated customer messaging.
Continue building
Next steps
Start here
A plain-language map of Free Sandbox, paid sender modes, credentials, and the first successful request.
Free Sandbox quickstart
The shortest beginner path from a verified account to a queued Free Sandbox OTP.
Glossary
Understand workspaces, keys, senders, receivers, queue states, webhooks, and idempotency.
Authentication and access
HookMessage separates customer API keys, dashboard sessions, and internal platform access.