BillRun uses a role-based access control (RBAC) model to manage what authenticated users are allowed to see and do within the system.
Roles are evaluated after successful authentication, regardless of whether authentication is performed locally or via an external Identity Provider.
Each user in BillRun is assigned one or more roles.
Roles determine the level of access across the BillRun platform, including administrative functions, operational actions, and reporting capabilities.
Currently, BillRun supports four predefined roles:
These roles are intentionally coarse-grained to simplify administration and reduce the risk of misconfiguration.
The admin role provides full administrative access to BillRun.
- Full access to all modules
- System and configuration management
- User and role management
- Access to all operational, billing, and CRM functions
- Access to all reports and sensitive data
- System administrators
- Platform owners
- Trusted operational leads
The write role provides operational access with modification capabilities.
- Create, update, and manage operational data
- Execute billing-related actions
- Perform CRM operations
- View reports and operational data
- No access to system-level configuration
- No user or role administration
- Operations teams
- Billing analysts
- CRM operators
The read role provides view-only access to the system.
- View operational and billing data
- View CRM entities
- Read-only access to dashboards and screens
- No data modification
- No operational execution
- No configuration access
- Support teams
- Auditors
- External stakeholders requiring visibility only
The reports role provides access limited to reporting and analytics.
- Access to reports and analytics views
- Export report data (where enabled)
- No access to operational screens
- No data modification
- No system or configuration access
- Finance teams
- Business analysts
- Management and executives
¶ Role Precedence and Enforcement
- The
admin role supersedes all other roles
- If a user is assigned multiple roles, the most permissive role applies
- Role enforcement is consistent across:
- UI access
- API access
- Background operations
For local users:
- Roles are assigned directly within BillRun
- Role changes take effect immediately
When using an external Identity Provider:
- Roles are derived from claims returned by the provider
- Role mapping is explicit and deterministic
- BillRun does not infer or auto-assign roles
Refer to the Login with External Identity Providers documentation for role claim structure.
- Grant the
admin role sparingly
- Avoid sharing accounts across users
- Review role assignments periodically
- Use the
read or reports roles for audit and compliance access
- Align external IdP roles with BillRun roles explicitly
The current role model is designed for simplicity and stability.
Future versions may introduce:
- Fine-grained permissions
- Module-specific roles
- Custom role definitions (Enterprise Edition)
These enhancements will be backward-compatible with existing roles.