Administration

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.

Rotate keys when they may be exposed. Revoke clients that are no longer needed. Assign sender IDs narrowly so a compromised key has limited reach.

API keys are write-only secrets. The raw key is returned once on create or rotation; after that the platform stores only the hash.

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.

Assign only the sender IDs each integration needs. A checkout service, support tool, and OTP service should usually use separate keys so each can be revoked or rotated independently.

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.

GET/api/customer/api-clients

List API clients for the current customer workspace.

POST/api/customer/api-clients

Create an API client and return the raw `api_key` once.

Parameter	Type	Description
`name`required	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.

PATCH/api/customer/api-clients/{client_id}

Update name, role, or metadata for an API client.

POST/api/customer/api-clients/{client_id}/rotate-key

Generate a new raw `api_key` once and replace the stored key hash.

POST/api/customer/api-clients/{client_id}/revoke

Revoke an API client so future integration requests fail.

PUT/api/customer/api-clients/{client_id}/senders

Replace sender assignments for the API client.

Parameter	Type	Description
`sender_ids`required	uuid[]	Unique sender IDs, max 100.

Verify assigned senders

After creating a key, call `GET /api/senders` from your backend with that same key. The response should include every sender the integration is allowed to use.

If the sender list is empty, assign a connected sender to the API key in the dashboard before attempting to send messages.

GET/api/senders

Return senders visible to this API key.

Parameter	Type	Description
`x-api-key`required	header	Customer API key created in the dashboard.

200 response

json

[
  {
    "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.

Next steps

Quickstart

A practical path from empty workspace to a working server-side integration.

Authentication and access

HookMessage separates customer API keys, dashboard sessions, and internal platform access.

Workspaces

A workspace is the tenant boundary for every customer resource.

Senders and sessions

A sender is the WhatsApp number used to deliver messages for a workspace.