Getting Started

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.

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 can be restricted to `send_message` or `otp`, and it can be assigned to one or more sender IDs.

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.

GET/api/senders

With 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-key`required	header	Customer API key for integration requests.

200 response

json

[
  {
    "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"
  }
]

Admin and customer routes

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.

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.

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.

Send customer messages

Use `/api/messages/send` for opted-in, application-triggered customer communication.