Roles & Permissions

Whatomate 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

System Roles

Three system roles are created automatically for each organization:

Role	Permissions granted
Admin	Every permission in the catalogue below.
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, chat:read, chat: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, but they are not frozen. Super admins can edit the permissions of a system role, and anyone with roles:write can edit its description. Only deletion of the three system roles is blocked.

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 — exactly the permissions returned by GET /api/permissions.

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.chatbot	read, write	Chatbot settings
settings.sso	read, write	Single sign-on configuration
accounts	read, write, delete	WhatsApp account settings
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	Chatbot AI contexts
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	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, write, delete, assign	Organizations; assign manages members
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.calling, 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/PUT /api/org/settings (the General and Calling settings tabs) currently require authentication only — no permission is checked. The one exception is the Meta App credential fields (meta_app_id, meta_config_id, meta_app_secret), which require accounts:write.

Permission Matrix

When creating or editing a role, you'll see a permission matrix organized by resource:

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

Effective permissions are cached in Redis for 6 hours, but editing a role or changing a user's role explicitly invalidates the cache for every affected user, so changes take effect on the next request without waiting for the TTL or 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

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
Keyword rules	chatbot.keywords
Chatbot flows	flows.chatbot
AI contexts	chatbot.ai
Transfer queue	transfers
General settings	settings.general
Accounts	accounts
Canned Responses	canned_responses
Users	users
Roles	roles
Teams	teams
API Keys	api_keys
Webhooks	webhooks
SSO	settings.sso
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