Roles & Permissions

Soosh provides a flexible role-based access control (RBAC) system that allows you to define custom roles with granular permissions.

Overview

The permission system is built around:

• Permissions: Fine-grained access controls for specific actions on resources (e.g., users:write, contacts:read)
• Roles: Collections of permissions that can be assigned to users
• System Roles: Pre-defined roles (Admin, Manager, Agent) that cannot be deleted

Workspace components

Platform administrators choose which components a workspace can use under Platform → Organizations → organization → Features. Each component is switched on or off on its own: for example Contacts without Tags, or Call logs without Outgoing calls. Some components need another one (Conversation assignment needs Inbox; Keyword replies need the Bot; Customer memory needs AI replies), and the editor turns them on or off together after asking. Members, teams, roles, general settings, billing and audit logs are required and always available. Roles grant actions within the available components. Access also requires active organization membership and any assignment or record-visibility rules.

New organizations start with optional components unavailable. Roles, the role editor and API-key scopes show only the permissions of components the workspace has, plus the governance permissions every workspace has; role counts count those. Built-in roles are always listed; a custom role with nothing left says No enabled permissions. When a component is taken away, roles keep their saved grants for it: they give no access, the role editor notes how many are kept, and saving the role doesn’t remove them unless you choose Remove them (you must hold those permissions yourself). Adding the component back makes the kept ones work again, so remove those you don’t want before it’s added. Tenant role administrators can delegate only permissions they hold and cannot edit their own role. If a role or the workspace’s components change while a role is open, saving asks you to reload it, so no grant is dropped unseen.

Platform services — Organizations, Sign-in (SSO), WhatsApp app and Webhook inbox — are managed only by super administrators. SSO availability is shared across organizations and cannot be disabled through organization allocations or role grants.

System Roles

Four system roles are created automatically for each workspace:

Role	Permissions granted
Owner	Every customer permission in the catalogue below, including billing:write. Held by exactly one member: the customer named when the workspace was created. Its permissions are fixed and cannot be edited, even by platform staff.
Admin	Every customer permission except billing:write. In workspaces created before owners existed, roles keep billing:write until the workspace gets its first owner; that assignment removes it from every role except Owner, so the owner re-approves who can change billing.
Manager	Everything except: users, roles, SSO settings, API keys, audit logs, organization write/delete/assign (organizations:read only), and teams write/delete (teams:read only).
Agent	accounts:read, catalogs:read, chat:read, chat:write, chatbot.memory:read/write, contacts:read, tags:read, analytics.agents:read, transfers:read/write/pickup, canned_responses:read, call_transfers:read/write, outgoing_calls:read/write. Note agents deliberately have no call_logs:read — they see only their own calls.

Note

System roles cannot be deleted. Super admins can edit the permissions of the Admin, Manager and Agent roles; nobody can edit the Owner role’s permissions. Anyone with roles:write can edit a system role’s description. The name “owner” is reserved for the built-in role.

Workspace owner

Every action the owner can take is still limited to the modules enabled for the workspace; the owner never gains platform authority.

• Only the owner manages administrators. A role is administrator-level when it holds users:write, roles:write and organizations:assign (the built-in Admin role, or any custom role with all three). Only the owner, or platform staff, can assign such a role, change or remove a member who holds one, or edit an administrator-level role’s permissions. Admins still manage Managers, Agents and other non-administrator roles.
• Billing changes are owner-controlled. Only the Owner holds billing:write by default. The Owner can delegate it through a custom role (for example, to a finance contact), but only the Owner or platform staff can create, edit or assign a role that includes billing:write, or change or remove a member who holds one. A delegate can change billing but cannot pass it on. Everyone with billing:read can still view billing.
• Nobody can demote or remove the owner through member or user management, and the Owner role cannot be assigned there. Platform staff cannot deactivate the owner’s account or make it a platform administrator while it owns a workspace.
• The owner can transfer ownership in Settings → General → Workspace owner: choose an active member who has set their password, then confirm with your current password. You stay in the workspace as an Admin and lose billing control; billing delegates you approved keep it. If you sign in with SSO and don’t know your password, set one with Forgot password first.
• Platform recovery: platform staff can change the owner from Platform → Workspaces → workspace → Workspace owner, recording a confirmation reference and reason after verifying the request with the current owner (or the customer’s verified business contact). The previous owner stays as an Admin. Every ownership change is audited.
• Workspaces created before owners existed show Owner needed until staff assign one. Until then, admins cannot manage other admins; only platform staff can.

Custom Roles

Create custom roles to match your organization’s needs. For example:

• Support Lead: Can manage contacts and view analytics, but not manage users
• Campaign Manager: Can create/manage campaigns and templates only
• Read-Only Auditor: Can view all data but not make changes

Creating a Custom Role

1. Go to Settings → Roles
2. Click Add Role
3. Enter a name and description
4. Select permissions from the permission matrix
5. Click Create

Permissions

Permissions follow the format resource:action. Available actions are:

Action	Description
read	View the resource
write	Create or modify items (there is no separate create/update — both are write)
delete	Remove items
sync	Sync from an external source (templates)
execute	Run the resource (campaigns)
import	Bulk-import records (contacts)
export	Bulk-export records (contacts)
pickup	Claim a queued item (transfers)
assign	Manage organization members (organizations:assign)

Note

There is no create or update action. Creating a new item and editing an existing one both require the write action on that resource.

Available Resources

This is the complete seeded catalogue. GET /api/permissions returns the part of it your workspace has: permissions of components it doesn’t have, and platform permissions, are left out.

Resource	Actions	Description
users	read, write, delete	User management
teams	read, write, delete	Team management
roles	read, write, delete	Role management
settings.general	read, write	General organization settings
settings.calling	read, write	Organization calling settings
settings.chatbot	read, write	The bot’s messages, session timeout and sessions, and AI settings while the AI component is on
chatbot.routing	read, write	Agent routing settings: queue pickup, returning customers, current conversation only
chatbot.hours	read, write	Business hours and the out-of-hours reply
chatbot.sla	read, write	SLA targets, escalation and client inactivity
accounts	read, write, delete	WhatsApp account settings
catalogs	read, write, delete	Product catalogs and products
templates	read, write, delete, sync	Message template management; sync pulls templates from Meta
flows.whatsapp	read, write, delete	WhatsApp Flows (interactive forms)
flows.chatbot	read, write, delete	Chatbot flow management
campaigns	read, write, delete, execute	Campaign management; execute starts/retries a send
chatbot.keywords	read, write, delete	Chatbot keyword auto-reply rules
chatbot.ai	read, write, delete	Knowledge base (AI contexts). AI settings use settings.chatbot while the AI component is on
chatbot.memory	read, write	View and edit customer memory beside a chat
chat	read, write	View conversations (read) and send messages (write)
chat.assign	write	Assign conversations to agents
contacts	read, write, delete, import, export	Contact management and bulk import/export
tags	read, write, delete, import, export	Contact tag management
analytics	read, write, delete	View the analytics dashboard (read); write/delete govern dashboard widgets
analytics.agents	read	Agent performance analytics
transfers	read, write, pickup	Chatbot-to-agent transfer queue
webhooks	read, write, delete	Outbound webhook configuration
api_keys	read, write, delete	API key management
canned_responses	read, write, delete	Saved reply templates
custom_actions	read, write, delete	Custom action buttons
organizations	read, assign	Tenant member visibility and assignment
call_logs	read	Voice call history
ivr_flows	read, write, delete	IVR call flow definitions
call_transfers	read, write	Voice call transfers
outgoing_calls	read, write	Outbound calling
audit_logs	read	Audit trail (read-only)

Note

settings.notification and the settings.chatbot.* sub-resources (.messages, .agents, .hours, .sla, .ai) appear in audit log entries as resource labels, but they are not grantable permissions and are never seeded.

Caution

GET /api/org/settings requires authentication only. PUT /api/org/settings checks settings.general:write or settings.calling:write for the fields it changes. The Meta app used for Embedded Signup is platform-wide and managed by super admins only, via GET/PUT /api/admin/platform/meta-app.

Permission Matrix

When creating or editing a role, you’ll see a permission matrix grouped by module, with resources inside each group. Only the workspace’s components are listed:

Users
  ☑ Read users     (users:read)
  ☑ Write users    (users:write — create or edit)
  ☐ Delete users   (users:delete)

Contacts
  ☑ Read contacts     (contacts:read)
  ☑ Write contacts    (contacts:write)
  ☐ Delete contacts   (contacts:delete)
  ☐ Import contacts   (contacts:import)
  ☐ Export contacts   (contacts:export)

Assigning Roles to Users

1. Go to Settings → Users
2. Click on a user or create a new one
3. Select a role from the dropdown
4. Save changes

Tip

Permissions are read from the database on every request, so role and membership changes take effect on the next request without logging out.

Multi-Organization Access

Users can belong to multiple organizations, each with a different role. The organization switcher appears in the sidebar for users who are members of more than one organization.

Organization Switching

When switching organizations:

1. New JWT tokens are issued scoped to the target organization via POST /api/auth/switch-org
2. The user’s role and permissions are loaded from their membership in the target organization
3. All data views refresh to show the selected organization’s data
4. The selected organization persists across page navigation

Cross-Organization Members

Users added to an organization from another org appear with a Member badge in the user list. Members have limited management:

• Role updates — only the org-specific role can be changed
• Removal — removes the user from the organization without deleting their account
• Other fields (email, password, name, active status) are managed in the user’s home organization

Closed workspaces

Platform support can close a workspace, for example while an account is suspended. Closing deletes nothing: data, members, roles, enabled modules, the wallet and history are all kept.

While a workspace is closed:

• Members see Workspace closed — contact support instead of the workspace, and can still open their other workspaces from that page or the switcher, where the closed one is marked Closed. Signing in takes you to another workspace you belong to, if you have one.
• API keys for the workspace stop working, and nothing is sent from it: no messages, campaigns, chatbot or AI replies, calls, outgoing webhooks, store automations or auto-recharges.
• Messages and calls that arrive are acknowledged to WhatsApp but not kept, so they don’t appear after it reopens. Delivery and read receipts for messages already sent are still recorded.

When support reopens the workspace, everything works again, but nothing restarts on its own: campaigns that were running or scheduled stay Paused until you resume them, and store automations only message orders and checkouts from after the reopen.

Deleted workspaces

Platform support can also delete a workspace, for example when an account ends. A deleted workspace is closed as well, and it disappears for its members: it is no longer listed in the switcher, and anyone signed in to it is signed out. Nothing is removed, though: support can restore the workspace with all its data, members and history. It comes back closed until support reopens it. Its WhatsApp numbers can’t be connected to another workspace while it is deleted.

The workspace Owner can’t close or delete their own workspace; contact support.

Super Admin

Super admins have additional privileges:

• Access to all organizations, even without explicit membership
• Can switch to any organization using the X-Organization-ID header
• Can create new organizations

Caution

The X-Organization-ID header switches the org for a single request. A super admin may name any existing organization; anyone else may only name an org they hold a user_organizations membership in. An unusable value is ignored silently — the request falls back to the org in the caller’s JWT rather than failing. POST /api/auth/switch-org is the durable alternative: it re-issues the auth cookies scoped to the new org, so every later request follows without the header.

UI Behavior

The frontend dynamically adapts based on user permissions:

Sidebar Menu

Each route declares the resource it needs in its meta.permission, and the router hides the menu item and blocks navigation when the user lacks <resource>:read:

Area	Resource
Dashboard / Analytics	analytics
Agent Analytics	analytics.agents
Chat	chat
Contacts	contacts
Tags	tags
Templates	templates
WhatsApp Flows	flows.whatsapp
Campaigns	campaigns
Chatbot settings & builder	settings.chatbot (agent routing, business hours and SLA tabs need their own: chatbot.routing, chatbot.hours, chatbot.sla)
Keyword rules	chatbot.keywords
Chatbot flows	flows.chatbot
AI contexts	chatbot.ai
Customer memory	chatbot.memory
Transfer queue	transfers
General settings	settings.general
Accounts	accounts
Catalogs	catalogs
Canned Responses	canned_responses
Users	users
Roles	roles
Teams	teams
API Keys	api_keys
Webhooks	webhooks
SSO	super admins only
Custom Actions	custom_actions
Audit Logs	audit_logs
Call Logs	call_logs
IVR Flows	ivr_flows
Call Transfers	call_transfers

Page Access

If a user tries to access a page they don’t have permission for, they are redirected to the first accessible page.

Action Buttons

Create, edit, and delete buttons are shown only if the user has the corresponding permission. For example, the “Add User” button only appears if the user has users:write permission.

API Authorization

All API endpoints check permissions before processing requests:

# Returns 403 if user lacks users:read permission
GET /api/users

# Returns 403 if user lacks campaigns:write permission
POST /api/campaigns

Response for Unauthorized Access

A missing permission returns 403 with a generic message — the specific resource:action is not disclosed. An unauthenticated request returns 401 Unauthorized instead.

{
  "status": "error",
  "message": "Insufficient permissions",
  "data": null
}

Best Practices

1. Principle of Least Privilege: Assign only the permissions users need
2. Use Custom Roles: Create roles that match job functions rather than assigning system roles
3. Regular Audits: Periodically review role assignments and permissions
4. Document Roles: Use meaningful names and descriptions for custom roles