Permissions
Define custom roles and manage the 65-key permission catalog in VoiceCenter.
VoiceCenter includes a granular permission system built around custom tenant roles and a 65-key permission catalog. This allows you to define exactly what each role can access, down to individual features and actions.
How Permissions Work
Every API endpoint and navigation item in VoiceCenter is protected by a permission key. When a user performs an action, the system checks whether their assigned role includes the required permission key.
The permission flow:
- An administrator creates a custom role (TenantRole).
- The administrator assigns permission keys to that role.
- Users are assigned the role.
- The system enforces the role's permissions on every request and hides unauthorized navigation items.
The Permissions Page
Navigate to Settings > Permissions to manage roles and their permissions. The page has three tabs:
| Tab | Purpose |
|---|---|
| Roles | Create, edit, and delete custom roles |
| Permission Catalog | Browse all 65 available permission keys with descriptions |
| Assignments | View which users have which roles and make bulk changes |
Creating a Custom Role
Go to the Roles tab
Open Settings > Permissions and select the Roles tab.
Click Create Role
Click the Create Role button and enter a name for the role (e.g., "Junior Agent", "Finance Viewer", "Team Lead").
Select permission keys
Check the boxes next to each permission key this role should have. Use the search bar and category filters to find specific keys quickly.
Save the role
Click Save. The role is now available for assignment to users.
Permission Key Categories
The 65 permission keys are organized into categories:
| Category | Example Keys | Controls |
|---|---|---|
| Users | users.view, users.create, users.edit, users.delete | User account management |
| Teams | teams.view, teams.create, teams.edit, teams.delete | Team management |
| PBX | extensions.manage, ivr.manage, queues.manage, ring_groups.manage | PBX configuration |
| Numbers | numbers.view, numbers.routing, numbers.request | Number management and routing |
| Voice | calls.make, calls.receive, recordings.view, recordings.download | Call operations |
| Monitoring | monitor.view_own, monitor.view_team, monitor.view_all, monitor.listen, monitor.whisper, monitor.barge | Live call supervision |
| Call Logs | call_logs.view_own, call_logs.view_team, call_logs.view_all, call_logs.export | Call history access |
| Billing | billing.view, billing.invoices, billing.wallet, billing.plans | Financial data |
| Analytics | analytics.view, analytics.export | Reporting and dashboards |
| Settings | settings.general, settings.api_keys, settings.webhooks, settings.ip_allowlist | Tenant configuration |
| Operations | caller_id.manage, fraud_limits.manage, blocked_destinations.manage | Telecom controls |
Tiered visibility keys
Several permission keys support tiers: view_own, view_team, and view_all. For example, an agent with call_logs.view_own sees only their calls, while a supervisor with call_logs.view_team sees all calls from their team. The view_all tier grants cross-team access.
Built-In Roles vs. Custom Roles
VoiceCenter ships with three built-in roles that cannot be deleted:
| Role | Permissions |
|---|---|
| Admin | All 65 permission keys |
| Supervisor | Monitoring, team-scoped logs, reporting, queue management |
| Agent | Make/receive calls, view own logs, after-call work |
Custom roles let you create variations. Common examples:
- Finance Viewer --
billing.viewandbilling.invoicesonly, no call or PBX access. - QA Analyst --
recordings.view,call_logs.view_all, andanalytics.viewfor quality review without call-making ability. - Junior Agent -- Same as Agent but without
recordings.downloadorcall_logs.export.
Assigning Roles to Users
You can assign roles in two places:
- User edit form -- When creating or editing a user under Settings > Users, select the role from the dropdown.
- Assignments tab -- On the Permissions page, the Assignments tab shows all users and their roles. Use it for bulk reassignment.
How Enforcement Works
Permission enforcement happens at two levels:
- Frontend -- Navigation items, buttons, and page sections are hidden when the user lacks the required key. This prevents confusion but is not a security boundary.
- Backend -- Every API endpoint checks the user's role permissions via the
@RequirePermissiondecorator. Unauthorized requests return a 403 Forbidden response regardless of what the frontend shows.
Always test new roles
After creating a custom role, log in as a user with that role to verify the experience. Check that they can access what they need and that restricted areas are properly hidden.