Team & Roles

A WaSphere workspace can be shared with a team. Invite teammates by link, put them in an authority tier, and — for agents — grant exactly the capabilities they need through a named custom role.

Authority tiers

Every member holds one of three tiers:

Tier	Capabilities
Owner	Everything. The workspace owner.
Admin	Everything. Full access, without being the owner.
Agent (MEMBER)	Exactly the capabilities of their assigned custom role — nothing more.

Owners and Admins always resolve to the complete capability set, so custom roles are irrelevant for them. An Agent with no role assigned has no capabilities granted through one.

Capabilities

A custom role is a named set of capabilities. There are seven:

Capability	Grants
inbox	View and reply in the Inbox
contacts	View and edit the contact book
messages	The Messages page — manual and API sends
sessions	Manage WhatsApp connections (link and unlink numbers)
webhooks	Manage outbound webhooks
api_keys	Manage API keys — machine credentials
settings	Workspace settings, branding, and the danger zone

Capabilities gate what people can do in the dashboard. They are a separate system from API key permission scopes, which gate what machine clients can do over the public HTTP API. A support agent's login and your integration's API key are governed independently.

Example roles

Role name	Capabilities
Support	inbox, contacts
Marketing	inbox, contacts, messages
Developer	api_keys, webhooks, sessions

Roles are defined per workspace and reused across members and invites — change a role's capabilities and every member holding it is updated.

Managing the team

Team management lives at Dashboard → Team. The API is under the workspace:

GET    /workspaces/{workspaceId}/my-role
GET    /workspaces/{workspaceId}/members
PATCH  /workspaces/{workspaceId}/members/{userId}
DELETE /workspaces/{workspaceId}/members/{userId}

GET    /workspaces/{workspaceId}/roles
POST   /workspaces/{workspaceId}/roles
PATCH  /workspaces/{workspaceId}/roles/{roleId}
DELETE /workspaces/{workspaceId}/roles/{roleId}

GET    /workspaces/{workspaceId}/invites
POST   /workspaces/{workspaceId}/invites
DELETE /workspaces/{workspaceId}/invites/{inviteId}

Create a role:

curl -X POST https://api.yourdomain.com/workspaces/{workspaceId}/roles \
  -H "Authorization: Bearer wsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support",
    "capabilities": ["inbox", "contacts"]
  }'

Only the seven capability strings above are accepted; anything else is rejected by validation.

Invites

Invite a teammate by generating a link. The invite carries the tier they join as, and — for Agent-tier invites — the custom role assigned on acceptance.

curl -X POST https://api.yourdomain.com/workspaces/{workspaceId}/invites \
  -H "Authorization: Bearer wsk_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "role": "MEMBER", "customRoleId": "..." }'

The response contains the raw token, the ready-to-share inviteUrl, the role, expiresAt, and whether the invite was emailed.

Invites expire after 7 days. The invitee opens the link, sets their own password, and joins the workspace with the tier and role baked into the invite — you never handle their password. Pending invites are listed until accepted or expired, and can be revoked before use.

If SMTP is configured, the invite link is emailed automatically. With SMTP left unset, invites still work exactly as before — you just copy the link and send it yourself.

Removing access

Deleting a member removes their access to the workspace immediately. Deleting a custom role does not delete the members holding it — their role reference is cleared, leaving them as Agents with no granted capabilities, which is the safe direction to fail.

Related

• API keys — machine credentials and permission scopes
• Inbox — the shared workspace most agents live in
• Contacts — the shared contact book