Workspaces and team

A workspace is one business: its channel, its customers, its conversations, its workflows. Everything in this API belongs to exactly one.

You only ever see your own workspace

A record belonging to another workspace comes back as 404, not 403. There is no way to discover that an id exists somewhere else — from inside your workspace, it does not.

Your workspaces

GET   /v1/workspaces/current   the one your token is scoped to
GET   /v1/workspaces/mine      every one you belong to, with your role
PATCH /v1/workspaces/current   rename it (owners only)
PUT   /v1/workspaces/current/retention
                               how long message text is kept (owners only)
PUT   /v1/workspaces/current/idle
                               hours of silence before a conversation counts
                               as quiet, 1 to 23 (owners only)

Each access token is scoped to exactly one workspace, which is why no other endpoint takes a workspace id. Your first workspace is created when you sign up, and you are its owner.

More than one business

POST /v1/workspaces
{ "name": "Ada Shoes" }

POST /v1/workspaces/{id}/switch
{ "refreshToken": "<the one you are leaving>" }

Creating a workspace makes you its owner; your token stays where it was. Switching returns a new token pair scoped to the workspace you name, with your role there - the same shape as login, without the password again. A workspace you do not belong to is 404, the same as one that does not exist.

The refresh token you leave is revoked

Send it with the switch and it stops working. Presenting a revoked refresh token afterwards is treated as theft and signs you out everywhere, exactly as it does after logout - so replace it wherever you stored it before making another call with it.

Workspace management is for people. An API key belongs to one workspace and gets 403 from these endpoints.

Members

GET  /v1/users        everyone here
GET  /v1/users/{id}   one member
GET  /v1/users/me     you, and your role
PATCH /v1/users/me    your own name or phone
DELETE /v1/users/{id} remove a member (owners only)

Two roles. staff does the daily work: reading and replying to conversations, managing customers, syncing templates, and reading everything else. owner can additionally change what the workspace is — the rule is that anything which alters what gets sent automatically, who can get in, or which credentials exist needs an owner:

connect, rotate, disconnect or delete a channel - WhatsApp or Instagram
set the questions on an Instagram profile
create, publish, enable or disable a workflow
draft a workflow from a description
write, change or delete a trigger of your own
write, send, stop or archive a campaign
merge two customers into one
invite people, and remove members
rename the workspace
set when a conversation counts as quiet
submit a new template to Meta, and delete one
issue or revoke API keys
add, change or remove webhooks
turn the AI assistant on or off, and set what it may say and spend
create, edit, publish, withdraw and delete business knowledge entries
set the monthly Engage credit spending limit
purchase Engage credits
write the weekly brief on demand
lift an opt-out

A staff member calling any of those gets 403.

You cannot remove yourself

A workspace with no owner is unadministrable, and the only fix is a platform administrator reaching into the database. Refused rather than allowed and regretted.

Invitations

POST /v1/users/invitations

{ "email": "colleague@example.com", "role": "staff" }

Sends an email with a single-use token. The invitee accepts it with POST /v1/auth/invitations/accept, choosing their own password — you never set one for them, and no endpoint will tell you whether they have.

GET    /v1/users/invitations       pending ones
DELETE /v1/users/invitations/{id}  revoke

Revoking kills the token. An invitation sent to the wrong address is undone by revoking it, not by hoping nobody clicks.

Invitation links are credentials

Anyone holding the link can join the workspace as the role it names. Accepting one is throttled per address for the same reason sign-in is: the endpoint verifies a password for an address that may already have an account, which makes it a password oracle if left open.

API keys →

Issuing, revoking, and the two paths a key can reach.