Skip to content
Whatomate

Roles & Permissions

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

Overview

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Multi-Organization Access

Section titled “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

Section titled “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

Section titled “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

Section titled “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

Section titled “UI Behavior”

The frontend dynamically adapts based on user permissions:

Section titled “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

Section titled “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

Section titled “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

Section titled “API Authorization”

All API endpoints check permissions before processing requests:

Terminal window
# 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

Section titled “Response for Unauthorized Access”
{
  "status": "error",
  "message": "Permission denied: users:create"
}

Best Practices

Section titled “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