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:create, 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	Description
Admin	Full access to all features including user and role management
Manager	Full access except user/role management and organization settings
Agent	Limited access - can only view/respond to assigned chats

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

Go to Settings → Roles
Click Add Role
Enter a name and description
Select permissions from the permission matrix
Click Create

Permissions

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

Action	Description
`read`	View the resource
`create`	Create new items
`update`	Modify existing items
`delete`	Remove items

Available Resources

Resource	Description
`users`	User management
`roles`	Role management
`teams`	Team management
`contacts`	Contact management
`messages`	Message sending/viewing
`templates`	Message template management
`campaigns`	Campaign management
`flows`	Chatbot flow management
`chatbot`	Chatbot settings
`webhooks`	Webhook configuration
`api_keys`	API key management
`organizations`	Organization and member management
`accounts`	WhatsApp account settings
`settings`	Organization settings
`analytics`	Analytics and reporting

Permission Matrix

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

Users
  ☑ Read users
  ☑ Create users
  ☐ Update users
  ☐ Delete users

Contacts
  ☑ Read contacts
  ☑ Create contacts
  ☑ Update contacts
  ☐ Delete contacts

Assigning Roles to Users

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

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:

New JWT tokens are issued scoped to the target organization via POST /api/auth/switch-org
The user’s role and permissions are loaded from their membership in the target organization
All data views refresh to show the selected organization’s data
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

UI Behavior

The frontend dynamically adapts based on user permissions:

Menu items are shown/hidden based on permissions:

Chat - Requires messages:read
Contacts - Requires contacts:read
Campaigns - Requires campaigns:read
Templates - Requires templates:read
Chatbot - Requires chatbot:read
Analytics - Requires analytics:read
Settings - Requires any settings-related permission

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:create 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:create permission
POST /api/campaigns

Response for Unauthorized Access

{
  "status": "error",
  "message": "Permission denied: users:create"
}

Best Practices

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