Workspaces
Understand how HookMessage scopes senders, API keys, messages, contacts, billing, and team access.
What belongs to a workspace
Every sender, API client, message, webhook, contact, segment, template, campaign, automation rule, team member, billing subscription, and audit log belongs to one workspace.
Dashboard users operate inside their current workspace. API keys are also workspace-scoped, so a key cannot send through senders from another workspace.
- Use one workspace per business, tenant, or isolated environment.
- Keep production and testing in separate workspaces when limits, senders, and billing must not mix.
- Use team roles to control who can manage senders, API keys, webhooks, billing, and security settings.
How integrations use workspace data
Your backend usually does not pass a workspace ID when sending messages. The API derives the workspace from the `x-api-key` header and validates sender access from that key.
To find the sender IDs available to an integration, call `GET /api/senders` with the same API key the integration will use for sending.
/api/sendersList senders assigned to the API key's workspace and client.
| Parameter | Type | Description |
|---|---|---|
x-api-keyrequired | header | Customer API key created in the dashboard. |
[
{
"sender_id": "9f4b5d4c-0000-4000-9000-123456789abc",
"workspace_id": "f2aa1d49-9f4b-4f37-9918-d8d8f13fb530",
"phone_number": "212612345678",
"display_name": "Main support",
"status": "connected",
"is_active": true
}
]Operational checklist
Before going live, confirm the workspace has an active plan, a server-side API key, the correct sender mode, and webhook or polling behavior for delivery status.
Managed routing does not expose a customer sender. Paid connected-sender mode requires at least one assigned number with `connected` status.
When multiple teams use the same workspace, rotate old API keys and keep sender assignments narrow so each integration only reaches the numbers it needs.
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.