Authentication and access
Understand API keys, customer sessions, internal access, and workspace isolation.
Authentication model
Customer integration endpoints use `x-api-key`. Customer dashboard pages use authenticated customer sessions. Internal platform tooling uses separate private service credentials.
Do not mix those trust levels in application code. A browser session should manage dashboard workflows, while your backend should call integration endpoints with a customer API key.
For normal customer integrations, the only credential your application needs is a dashboard-created API key sent in the `x-api-key` header.
- Client API key: use `x-api-key` from backend code for sender discovery, message send, OTP send, and message status.
- Internal platform credential: use `x-service-key` only for trusted platform operations and never in customer apps.
- Customer session: use dashboard pages and `/api/customer/*` routes for workspace management.
- Admin session: use platform operator routes only for internal administration.
Never expose keys in the browser
Do not put API keys or service keys in frontend bundles. All code samples assume a backend environment variable.
Client API keys
API clients are workspace-scoped. A key is restricted to `send_message` or `otp`. Sender behavior depends on whether the key uses managed routing or customer-connected senders.
When a request includes a sender outside the key assignment, the API rejects it. This is the main control that keeps one integration from sending through a different number.
Use separate keys for separate systems. For example, login OTP, checkout notifications, and support tooling should not share one key unless they truly need the same permissions.
- send_message role: can call `/api/messages/send` for normal outbound customer messages.
- otp role: can call `/api/otp/send` for verification-code flows.
- Managed routingomit `sender_id`; HookMessage chooses an eligible platform sender.
- Connected sender assignmentlimits the customer-owned WhatsApp numbers the key may use.
- status revoked: rejects future requests while preserving historical records and audit logs.
/api/sendersWith a client API key, returns only senders assigned to that key. With a service key, returns the admin-visible sender list.
| Parameter | Type | Description |
|---|---|---|
x-api-keyrequired | header | Customer API key for integration requests. |
[
{
"sender_id": "9f4b5d4c-0000-4000-9000-123456789abc",
"workspace_id": "f2aa1d49-9f4b-4f37-9918-d8d8f13fb530",
"phone_number": "212612345678",
"display_name": "Main support",
"status": "connected",
"trust_tier": "trusted",
"daily_limit": 500,
"messages_sent_today": 12,
"is_active": true,
"connected_at": "2026-06-29T16:00:00.000Z",
"created_at": "2026-06-29T15:50:00.000Z"
}
]Advanced: management routes
Most integrations can skip this section. Use the customer dashboard to create keys, connect numbers, and configure billing.
Customer portal management routes use the authenticated customer workspace. Platform admin routes are internal and are not required for normal customer integrations.
Public integration docs should be followed with customer API keys. Use dashboard pages for workspace administration unless you are building trusted internal platform tooling.
- Dashboard API key management: use `/dashboard/api-clients`, backed by authenticated `/api/customer/api-clients` routes.
- Public customer integration: use `/api/senders`, `/api/messages/send`, `/api/otp/send`, and `/api/messages/{message_id}` with `x-api-key`.
- Internal platform tooling: use `/api/admin/*` only with trusted operator/service credentials.
- Do not use customer session cookies as a replacement for `x-api-key` in backend integrations.
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.
Workspaces
A workspace is the tenant boundary for every customer resource.