Get started

Workspaces, roles and team members

A workspace holds one team’s WhatsApp connection, inbox, contacts and settings. Every API key belongs to one workspace; browser sessions pick the workspace with the X-Tenant-ID header.

How do I select a workspace?

Caller	Workspace selection
API key	Automatic: the key’s own workspace. `X-Tenant-ID` or `?tenant=` is optional, but if sent it must match, or you get `403` with `API key belongs to a different workspace`.
Signed-in session	Required: send the workspace id in `X-Tenant-ID` (or `?tenant=`). Missing or malformed: `400` with `workspace required (X-Tenant-ID)`. Not a member: `403` with `forbidden`.

A signed-in user can list their workspaces and role in each with GET /api/me and create a new one with POST /api/tenants. Both are Console only.

What can each role do?

Role	Inbox	Administration
`owner`	All conversations	Everything, including adding admins and changing admin roles. Cannot be removed. One per workspace.
`admin`	All conversations	Members (agents), invites, API keys, webhooks, channel settings, automations, templates, knowledge, assigning conversations.
`agent`	Only conversations assigned to them; cannot start new chats	None.
API key	All conversations; can start chats	None (acts as an agent with access to the whole inbox).

How do members and invites work?

Add or invite a member with an email and role (admin or agent). If the email already has an account, the person is added immediately; otherwise an invite is created and emailed, valid for 7 days.
Only owners can add admins, change admin roles or remove admins.
Members have two ids: id (the membership, used by the member endpoints) and user_id (the person, used as assignee_id when assigning a conversation).
List members works with an API key, so integrations can map assignee_id to names. Every other member and invite endpoint is Console only.

Are workspaces billed separately?

When subscriptions are enforced, each workspace needs its own active subscription. Without one, workspace endpoints return 402 with subscription required and code: "payment_required".