clariBI includes five built-in roles—Owner, Administrator, Analyst, Member, and Viewer—but real organizations rarely fit neatly into five buckets. The custom role builder lets you create roles with exactly the permissions you need, nothing more. This guide walks through every permission category and shows practical examples of custom roles you might want to create.
When You Need Custom Roles
The built-in roles work well for small teams. But as your organization grows, you will hit situations where they do not fit:
- A department head who needs to manage their own team's dashboards but should not see billing or organization-wide settings
- An external contractor who needs to build reports but should not access raw data sources
- A compliance officer who needs read access to audit logs but should not modify any data
- A data engineer who manages data source connections but does not need report or dashboard permissions
Custom roles solve these problems by letting you grant exactly the permissions each person needs.
Tier requirement: Custom roles are available on Professional and Enterprise plans. Starter and Trial plans use the five built-in roles only.
Accessing the Role Builder
Navigate to Settings > Team > Roles. You will see the five default roles listed with their permission counts. Click the + Create Role button in the top right corner to open the role builder.
Understanding Permission Categories
clariBI organizes permissions into logical groups. Here is every category and what each permission controls:
Dashboard Permissions
| Permission | What It Controls |
|---|---|
dashboard.view | View dashboards shared with the user or their workspace |
dashboard.create | Create new dashboards from scratch or from templates |
dashboard.edit | Modify existing dashboards (layout, widgets, settings) |
dashboard.delete | Permanently delete dashboards |
dashboard.share | Share dashboards with other users, workspaces, or publicly |
Report Permissions
| Permission | What It Controls |
|---|---|
report.view | View generated reports |
report.create | Create and configure new reports |
report.edit | Modify report parameters, schedule, and distribution |
report.delete | Delete reports |
report.export | Export reports as PDF, CSV, or Excel |
report.schedule | Set up automated report delivery schedules |
Data Source Permissions
| Permission | What It Controls |
|---|---|
datasource.view | See configured data source names and status |
datasource.create | Connect new data sources |
datasource.edit | Modify connection settings, sync schedule, field mappings |
datasource.delete | Remove data source connections |
datasource.sync | Trigger manual data syncs |
Analysis Permissions
| Permission | What It Controls |
|---|---|
analysis.view | View analysis results and AI-generated insights |
analysis.create | Run new analyses and use conversational analytics |
analysis.export | Export analysis results |
Team & Organization Permissions
| Permission | What It Controls |
|---|---|
team.view | View team member list and roles |
team.invite | Invite new members to the organization |
team.manage | Change member roles, deactivate accounts |
team.remove | Remove members from the organization |
Workspace Permissions
| Permission | What It Controls |
|---|---|
workspace.view | View workspaces the user is a member of |
workspace.create | Create new workspaces |
workspace.edit | Rename workspaces, modify settings |
workspace.manage_members | Add and remove members from workspaces |
Billing Permissions
| Permission | What It Controls |
|---|---|
billing.view | View current plan, usage, and invoices |
billing.manage | Change plans, update payment methods, manage subscriptions |
Administration Permissions
| Permission | What It Controls |
|---|---|
admin.audit_log | View the audit log of all actions in the organization |
admin.security | Manage security settings (MFA requirements, session policies) |
admin.api_keys | Create and revoke API keys |
admin.roles | Create and modify custom roles (this permission) |
Building a Custom Role: Step by Step
Step 1: Name and Describe the Role
Give the role a clear name that describes its purpose, not its holder. "Dashboard Builder" is better than "John's Role." Add a description explaining when this role should be assigned. Future administrators will thank you.
Step 2: Start From a Base
The role builder lets you start from scratch or clone an existing role. If the custom role is close to one of the built-in roles, clone it and modify the differences. This is faster and reduces the chance of missing a permission.
Step 3: Toggle Permissions
Work through each permission category. For every permission, ask: "Does someone in this role need to do this?" If the answer is no, leave it off. If you are unsure, leave it off—you can always add permissions later, but revoking them after someone has been relying on access is awkward.
Step 4: Review and Save
Before saving, the role builder shows a summary of all selected permissions grouped by category. Review this carefully. Pay special attention to delete and manage permissions, which carry the most risk.
Click Create Role to save. The new role immediately appears in the roles list and can be assigned to team members.
Practical Role Examples
Department Dashboard Manager
For team leads who manage their department's dashboards but should not touch data sources or billing:
- Dashboard: view, create, edit, share (no delete)
- Report: view, create, export
- Analysis: view, create
- Workspace: view, edit, manage_members
- Team: view
- Everything else: off
External Consultant
For contractors who build reports but should have minimal access:
- Dashboard: view, create, edit
- Report: view, create, edit, export
- Analysis: view, create, export
- Workspace: view
- Everything else: off
Data Engineer
For team members who manage data infrastructure but do not build dashboards:
- Data Source: view, create, edit, delete, sync
- Dashboard: view (read-only so they can verify data appears correctly)
- Admin: audit_log, api_keys
- Team: view
- Everything else: off
Compliance Auditor
For compliance staff who need visibility but should not modify anything:
- Dashboard: view
- Report: view
- Data Source: view
- Analysis: view
- Team: view
- Admin: audit_log
- Everything else: off
Common Mistakes to Avoid
Creating Too Many Roles
If you end up with 15 custom roles for a 20-person team, something has gone wrong. Aim for roles that cover job functions, not individuals. Most organizations of 50 people or fewer need the five built-in roles plus 2-4 custom ones.
Granting Delete Without Edit
If someone can delete a dashboard but cannot edit it, they can destroy work but cannot fix mistakes. Always pair delete permissions with the corresponding edit permission.
Forgetting to Review After Org Changes
When people change roles within the company, their clariBI role should change too. Set a quarterly reminder to review role assignments. The Team settings page shows each member's role and last active date, making it easy to spot stale assignments.
Ignoring the Principle of Least Privilege
Start with fewer permissions and add more as needed. It is tempting to be generous with access to avoid complaints, but over-permissioned accounts are a security risk. This is especially important for roles assigned to external contractors or temporary staff.
Modifying and Deleting Custom Roles
To edit a custom role, go to Settings > Team > Roles, find the role, and click the edit icon. You can add or remove permissions at any time. Changes take effect immediately for all users assigned to that role.
To delete a custom role, you must first reassign all users currently holding that role to a different one. clariBI will not let you delete a role that is still in use. This prevents accidentally stripping permissions from active users.
Built-in roles cannot be modified or deleted. They serve as a stable baseline that always exists regardless of custom role changes.
Wrapping Up
Custom roles give you fine-grained control over who can do what in clariBI. The key principle is simple: grant the minimum permissions needed for someone to do their job effectively. Start with the built-in roles, add custom roles only when you have a clear need, and review assignments periodically. For more on team management, see our RBAC and team management guide. For questions about which tier includes custom roles, check the billing page.
