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

Note

System roles cannot be deleted, but their permissions can be viewed (read-only).

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
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

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

Changes to permissions take effect immediately. Users will see updated menu items and access controls without needing to log 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 for direct API access is only respected for super admin users. Regular multi-org users must use the POST /api/auth/switch-org endpoint.

UI Behavior

The frontend dynamically adapts based on user permissions:

Sidebar Menu

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

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