Roles & Permissions
Optima Orbit uses a granular, code-based permission system to control access to every feature in the platform. Permissions are grouped into roles, and roles are assigned to users. This page explains how the system works and how to read permission codes throughout this documentation.
User tiers
The platform has three levels of user access:
| Tier | Scope | Description |
|---|---|---|
| Super Admin | Platform-wide | Full access to every feature across all organizations. Can manage modules, packages, system settings, and all org data. Bypasses all permission checks. |
| Organization Admin | Single organization | Manages settings, users, roles, and features for one organization. Access governed by assigned roles. |
| Regular User | Single organization | Day-to-day user. Sees only the features their role permits. |
Super Admin status is a flag on the user account (is_super_admin), not a role.
A Super Admin automatically passes every permission check in the system.
How permissions work
Permission codes
Every protected action in Orbit is gated by a permission code — a dot-separated string that follows the pattern:
<scope>.<module>.<action>
Examples:
| Code | Meaning |
|---|---|
| View Organization Employees | View the organization's user list |
| View Projects Page | View the projects list |
| View Tasks | View and manage tasks |
| View Marketing Suites lead management | View the CRM leads |
| Read Tickets & SLAs | View Resolve (service desk) tickets |
| View Module Registry | View the system module registry (admin only) |
Permission scopes
| Prefix | Scope | Who uses it |
|---|---|---|
org.* | Organization-level features | Org admins and users |
task.* | Task and project operations | Project team members |
mkt.* | Marketing and CRM (Orbit Pulse) | Marketing team |
sys.* | System administration | Super admins |
platform.* | Platform operations | Platform team |
partner.* | Partner portal | Channel partners |
Permission check flow
When you navigate to any feature:
The Permission Denied screen shows:
- The exact permission code required
- The category and module the permission belongs to
- A suggestion to contact your administrator
Multiple permissions (OR logic)
Some features accept multiple permission codes. If any one of the listed codes is present in your role, access is granted. This is shown in the docs as:
Permission required: View the Ticket Overview analytics tab (volume, status, priority, backlog age). or View the SLA & Compliance analytics tab (breach rate, FRT/resolution trends, OLA/vendor). or View the Agent Performance analytics tab (workload, resolution, FCR, AHT, CSAT per agent).
Managing roles
Organization roles
Organization admins can manage roles at Settings → Roles (/org/roles).
- Create custom roles with specific permission sets
- Clone existing roles as templates
- Assign roles to users at Settings → Users (
/org/users)
System roles
Super admins manage platform-wide roles at Admin → Roles (/admin/roles)
and can view the full permission matrix at Admin → Permissions
(/admin/permissions).
Access denied — what to do
If you see a Permission Denied screen or a feature is missing from your sidebar:
- Note the permission code shown on the denied screen
- Contact your organization administrator
- Ask them to add the required permission to your role at Settings → Roles
You can also click "View required access" on the 403 toast notification to see exactly which permission, category, and module you need.
FAQs & troubleshooting
Q: I'm an admin but I can't see certain settings tabs.
A: Being an "admin" doesn't automatically grant all permissions. Check that
your role includes the specific org.config.* permissions for the tabs you need.
Q: My role has the permission but the menu item is still hidden. A: The menu item may also require your organization to have the corresponding module package active. Contact your super admin.
Q: How do I know which permission a feature needs? A: Each feature page in this documentation lists the exact permission code under "Permission required". You can also check the Access Explorer at Admin → Access Explorer (super admin only).