Roles & Permissions
Roles & Permissions is a comprehensive access control system that allows you to manage who can access what features and perform which actions across your platform. By combining roles (collections of permissions) with workspace scoping, you can enforce least-privilege access principles and maintain robust security across all modules.
Understanding Roles & Permissions
The Roles & Permissions system is built on three core concepts that work together to provide granular access control:
Roles
Roles are collections of permissions grouped by job function or responsibility. Examples include "Admin", "Manager", "Sales Rep", or "Billing Manager". Users are assigned roles, which determine their access level.
Permissions
Permissions are granular actions that can be performed on modules. Each permission follows the format "module_action" (e.g., "contacts_view", "campaigns_create", "billing_edit"). Permissions are assigned to roles.
Modules
Modules are feature areas of the platform (Dashboard, Contacts, Campaigns, Billing, etc.). Each module has associated permissions (view, create, edit, delete, export) that control access to its features.
How It Works
The system follows a hierarchical structure:
Permission Flow
- Modules Define Features: Each module (Contacts, Campaigns, Billing, etc.) represents a feature area of the platform.
- Permissions Control Actions: Each module has permissions for actions like view, create, edit, delete, and export.
- Roles Group Permissions: Roles are created and assigned specific permissions from various modules.
- Users Get Roles: Users are assigned one or more roles, which grant them the permissions contained in those roles.
- Workspace Scoping: Access can be further restricted by workspace, allowing users to have different roles in different workspaces.
Example: A "Sales Manager" role might have "contacts_view", "contacts_edit", "campaigns_create", and "campaigns_edit" permissions. When assigned to a user, that user can view and edit contacts, and create and edit campaigns, but cannot delete contacts or access billing features.
Common Use Cases
Multi-Department Organizations
Create roles for different departments (Sales, Support, Billing, Management) with appropriate permissions. Sales teams can manage contacts and campaigns, while Billing teams only access billing features.
Client Access Control
Provide clients with read-only or limited access to their data. Create "Client" roles with view-only permissions for specific modules, ensuring clients can monitor but not modify operations.
Security & Compliance
Enforce least-privilege access by granting only necessary permissions. Restrict sensitive operations (delete, export, billing changes) to senior roles, reducing risk of accidental or malicious actions.
Multi-Workspace Management
Assign different roles to users in different workspaces. A user might be an Admin in one workspace but a Manager in another, providing flexible access control across organizational boundaries.
Key Benefits
Enhanced Security
Control access to sensitive features and data. Prevent unauthorized actions by restricting permissions to only what users need for their roles.
Simplified User Management
Assign roles instead of managing individual permissions for each user. When responsibilities change, update the role once and all users with that role are updated.
Workspace Flexibility
Users can have different roles in different workspaces. Perfect for agencies managing multiple clients or organizations with separate departments.
Audit & Compliance
Track who has access to what features. Review role assignments regularly to ensure compliance with security policies and organizational changes.
Creating Custom Roles
Creating custom roles allows you to tailor access control to your organization's specific needs.
Step 1: Navigate to Roles
-
1
Go to Roles & Permissions: Navigate to Roles & Permissions in the main navigation menu.
-
2
Click Roles: Select Roles from the Roles & Permissions submenu.
-
3
Click Add Role: Look for the Add Role button, typically at the top of the roles list.
Step 2: Define Role Details
Enter role information:
Required Information
- Role Name: A descriptive name that clearly indicates the role's purpose (e.g., "Billing Manager", "Sales Rep", "Support Agent")
- Description (Optional): Additional context about the role's responsibilities and when it should be used
Naming Best Practice: Use clear, descriptive names that indicate the role's purpose. Examples: "Workspace Admin", "Billing Manager", "Campaign Creator", "Read-Only Client". Avoid generic names like "Role 1" or "Test Role".
Step 3: Select Permissions
Choose which permissions this role should have:
Permission Types
View
Allows users to see and read data in a module. Required for any access to the module.
Create
Allows users to create new records (e.g., new contacts, campaigns, templates).
Edit
Allows users to modify existing records. Typically requires view permission as well.
Delete
Allows users to remove records. Use with caution - restrict to senior roles.
Export
Allows users to export data (e.g., download contact lists, call logs). May contain sensitive information.
Permission Selection: Select permissions by module. For example, if creating a "Sales Manager" role, you might select "contacts_view", "contacts_edit", "campaigns_view", "campaigns_create", and "campaigns_edit" permissions.
Step 4: Save and Assign
After selecting permissions:
- Review the selected permissions to ensure they match the role's intended purpose
- Click Save or Create Role to create the role
- The role will appear in your roles list and can be assigned to users
Recommended Role Templates
These role templates provide a starting point for common organizational needs:
Super Admin
Use Case: Platform owners and system administrators
Permissions: Full access to all modules and features, including billing keys, white label administration, and system settings.
Note: This role should be assigned to very few users. Super Admins bypass all permission checks.
Admin
Use Case: Workspace administrators and department managers
Permissions: Manage users, campaigns, settings, contacts, calls, and most features within assigned workspaces. Typically excludes billing and system-level settings.
Manager
Use Case: Team leads and operational managers
Permissions: Run campaigns, view analytics, manage contacts, create and edit templates. Typically cannot delete records or access billing.
User
Use Case: Day-to-day operators and team members
Permissions: View and use features for daily workflows. Limited configuration access. Can view contacts, calls, and campaigns but typically cannot create or edit.
Client
Use Case: External clients or stakeholders who need visibility
Permissions: Read-only access to specific modules. Can view reports, calls, and campaigns but cannot modify anything. Perfect for providing transparency without risk.
Permission Sets & Scopes
Understanding how to structure permission sets and apply scoping ensures effective access control.
Least-Privilege Principle
Always grant the minimum permissions necessary:
- Start with View: Most roles only need view permissions initially. Add create/edit permissions only when necessary.
- Restrict Destructive Actions: Delete and export permissions should be limited to senior roles. These actions can have significant consequences.
- Review Regularly: Periodically audit role permissions to ensure they still match current responsibilities.
- Document Exceptions: If a role needs elevated permissions, document why. This helps with audits and future reviews.
Grouping by Job Function
Organize roles by job function for clarity:
Sales Team
Example permissions:
- contacts_view, contacts_edit, contacts_create
- campaigns_view, campaigns_create, campaigns_edit
- calls_view
- templates_view
Support Team
Example permissions:
- contacts_view, contacts_edit
- calls_view, calls_edit
- appointments_view, appointments_create
- templates_view
Billing Team
Example permissions:
- billing_view, billing_edit
- wallet_view, wallet_refill
- subscriptions_view
- payment_methods_view, payment_methods_edit
Analyst/Reporting
Example permissions:
- dashboard_view
- calls_view, calls_export
- campaigns_view
- contacts_view, contacts_export
Workspace Scoping
Workspace scoping adds an additional layer of access control:
How Workspace Scoping Works
- Multi-Workspace Users: Users can belong to multiple workspaces, each with potentially different roles.
- Role Per Workspace: When assigning a role to a user, you specify which workspace(s) that role applies to.
- Isolated Access: A user's permissions in one workspace don't affect their access in another workspace.
- Flexible Management: Perfect for agencies managing multiple clients or organizations with separate departments.
Example: Sarah might be an "Admin" in the "Sales" workspace (allowing her to manage campaigns and contacts) but a "User" in the "Billing" workspace (only allowing her to view billing information).
Auditing & Maintenance
Regular auditing ensures your access control remains effective and aligned with organizational changes.
Regular Role Reviews
Schedule periodic reviews of role assignments:
Review Checklist
- Quarterly Reviews: Review all role assignments every quarter to ensure they still match current responsibilities.
- After Organizational Changes: When departments restructure or roles change, immediately review and update role assignments.
- User Departures: When users leave, immediately revoke their access. Don't wait for quarterly reviews.
- New Hires: Ensure new team members receive appropriate roles based on their job functions.
- Unused Roles: Identify and retire roles that are no longer in use to keep the system clean.
Action Logging
Track critical actions for security and compliance:
What to Monitor
- Permission Changes: Log when roles are modified or permissions are added/removed.
- Role Assignments: Track when users are assigned or removed from roles.
- Critical Actions: Monitor high-risk actions like campaign launches, billing changes, or data exports.
- Access Attempts: Review failed access attempts to identify potential security issues.
Best Practices
Role Design
- Clear Naming: Use descriptive names that clearly indicate the role's purpose. Avoid generic or ambiguous names.
- Avoid Overlap: Keep role responsibilities distinct. If roles overlap significantly, consider consolidating them.
- Document Purpose: Use role descriptions to document when and why a role should be used.
- Start Conservative: Begin with minimal permissions and add more only when needed. It's easier to grant permissions than to revoke them.
Permission Management
- Least Privilege: Always grant the minimum permissions necessary for a role to function.
- Group by Function: Organize permissions by job function rather than by individual needs.
- Restrict Destructive Actions: Limit delete and export permissions to senior roles only.
- Review Regularly: Periodically review role permissions to ensure they still match current needs.
User Assignment
- Assign Roles, Not Permissions: Always assign roles to users rather than individual permissions. This simplifies management.
- Workspace-Specific: Consider workspace context when assigning roles. A user might need different roles in different workspaces.
- Immediate Updates: Update role assignments immediately when responsibilities change. Don't wait for scheduled reviews.
- Remove Promptly: Revoke access immediately when users leave or change roles.
Troubleshooting
User cannot access a module or feature
Checklist:
- Check role assignment: Verify the user has a role assigned. Users without roles cannot access modules.
- Verify role permissions: Check that the user's role includes the necessary permissions for the module (e.g., "contacts_view" for Contacts module).
- Check workspace: Ensure the user has the role assigned in the correct workspace. Workspace scoping can restrict access.
- Verify module access: Some modules require specific permissions. Check that the role has at least "view" permission for the module.
- Super Admin bypass: Super Admins bypass all permission checks. If the user is a Super Admin, they should have access to everything.
Permission appears to be assigned but not working
Investigation Steps:
- Verify role assignment: Confirm the user actually has the role assigned. Check both the user's role list and workspace assignments.
- Check permission name: Ensure the permission name matches exactly (e.g., "contacts_view" not "contact_view"). Permission names are case-sensitive.
- Workspace context: If using workspaces, verify the role is assigned in the correct workspace. Permissions are workspace-scoped.
- Cache refresh: Sometimes permission changes require a cache refresh. Try logging out and back in, or clear the application cache.
- Check for conflicts: Ensure there are no conflicting permissions or role restrictions that might override the expected behavior.