Custom Roles & Granular Permissions

Overview

The five built-in roles (Owner, Administrator, Analyst, Member, Viewer) cover most organizations. But if your team structure requires more specific access controls -- a "Report Manager" who can generate reports but not manage data sources, or a "Dashboard Designer" who can edit dashboards but not run AI queries -- custom roles let you define exactly the permissions each role includes.

Custom roles are available on the Professional plan ($199/month) and Enterprise plan ($999/month).

Custom roles management page

Creating a Custom Role

Step 1: Open Role Management

Go to Settings > Organization > Roles.
You see the five built-in roles listed. Click + Create Custom Role.

Step 2: Define the Role

Role Name -- Choose a clear, descriptive name (e.g., "Report Manager", "Data Steward", "Marketing Analyst").
Description -- Explain the purpose of this role and who should be assigned it.
Base Template -- Optionally start from an existing role. Selecting "Analyst" as a base pre-selects all 14 Analyst permissions, which you can then add to or remove from.

Step 3: Select Permissions

The permissions editor shows all available permissions grouped by category. Check or uncheck each permission individually.

Permission Categories:

Dashboards

dashboards.view -- View published dashboards
dashboards.create -- Create new dashboards
dashboards.edit_own -- Edit dashboards you created
dashboards.edit_all -- Edit any dashboard
dashboards.delete_own -- Delete dashboards you created
dashboards.delete_all -- Delete any dashboard

Reports

reports.view -- View published reports
reports.generate -- Generate new reports (costs 2-5 AI credits)
reports.schedule -- Schedule recurring reports
reports.edit_own -- Edit reports you created
reports.edit_all -- Edit any report
reports.delete_own -- Delete reports you created
reports.delete_all -- Delete any report
reports.export -- Export reports to PDF, CSV, Excel

AI Analytics

analytics.query -- Run AI conversational queries (costs 1 AI credit each)
analytics.view_history -- View query history
analytics.view_all_history -- View all users' query history

Data Sources

data_sources.view -- View connected data sources
data_sources.create -- Add new data source connections
data_sources.edit -- Modify data source configuration
data_sources.delete -- Remove data source connections
data_sources.sync -- Trigger manual data syncs

Goals

goals.view -- View goals and progress
goals.create -- Create new goals
goals.edit_own -- Edit goals you created
goals.edit_all -- Edit any goal
goals.delete -- Delete goals

Collaboration

workspaces.view -- View workspace content
workspaces.create -- Create new workspaces
workspaces.manage -- Manage workspace settings and members
comments.create -- Add comments
comments.moderate -- Edit or delete anyone's comments
sharing.create -- Share content to workspaces
sharing.public -- Create public sharing links

Users & Administration

users.view -- View member list
users.invite -- Invite new members
users.remove -- Remove members
users.manage_roles -- Assign and change roles
users.reset_mfa -- Reset another user's MFA

Organization

org.settings -- Manage organization settings
org.audit_log -- Access audit logs
org.security_policies -- Set security policies
org.integrations -- Manage third-party integrations

Billing

billing.view -- View billing and usage information
billing.manage -- Change plans, update payment methods

Permission editor interface

Step 4: Save the Role

Click Save Role. The new role appears in the roles list and is immediately available for assignment.

Example Custom Roles

Here are practical examples to get you started:

Report Manager

A role for team members who focus on report creation and distribution.

Permissions: - dashboards.view - reports.view, reports.generate, reports.schedule, reports.edit_own, reports.delete_own, reports.export - analytics.query, analytics.view_history - data_sources.view - workspaces.view, sharing.create - comments.create

Dashboard Designer

A role for team members who build and maintain dashboards for others.

Permissions: - dashboards.view, dashboards.create, dashboards.edit_all, dashboards.delete_own - reports.view - data_sources.view - workspaces.view, workspaces.create, sharing.create, sharing.public - comments.create

Data Steward

A role focused on data source management without access to analytics or reporting.

Permissions: - data_sources.view, data_sources.create, data_sources.edit, data_sources.delete, data_sources.sync - dashboards.view - reports.view - org.audit_log - comments.create

External Consultant

A restricted role for outside partners who need limited analytics access.

Permissions: - dashboards.view - reports.view - analytics.query, analytics.view_history - workspaces.view - comments.create

Editing and Deleting Custom Roles

Editing a Role

Go to Settings > Organization > Roles.
Click the custom role you want to edit.
Modify the name, description, or permissions.
Click Save.

Permission changes take effect immediately for all users assigned to that role.

Deleting a Role

Click the three-dot menu next to the custom role.
Select Delete Role.
Choose a replacement role for users currently assigned to the deleted role.
Confirm the deletion.

You cannot delete built-in roles. You can only delete custom roles you created.

Assigning Custom Roles

Custom roles are assigned the same way as built-in roles:

Go to Settings > Team.
Find the member.
Click their current role badge.
Select the custom role from the dropdown.

Custom roles appear alongside the five built-in roles in the dropdown.

Limitations

Custom roles cannot exceed the Owner role's permissions. You cannot create a "Super Admin" with more access than the Owner.
The billing.manage permission should be assigned sparingly. Only give it to roles that need to change subscription or payment settings.
Custom roles are organization-wide. You cannot create a role that only applies to specific workspaces. Use workspace roles for workspace-level access control.
Maximum of 20 custom roles per organization.

API Access

Custom roles can be managed via the API:

# List all roles (built-in + custom)
curl -H "Authorization: Bearer <token>" \
  https://claribi.com/api/auth/rbac/roles/

# Create a custom role
curl -X POST \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Report Manager", "permissions": ["reports.view", "reports.generate"]}' \
  https://claribi.com/api/auth/rbac/roles/create/

See Endpoint Reference: Data Sources, Reports, Dashboards for full API documentation.

Best Practices

Start with built-in roles. Only create custom roles when the five defaults do not fit your needs.
Name roles by function, not person. "Marketing Analyst" is better than "Sarah's Role." People change; functions persist.
Document each role. Use the description field to explain the role's purpose and typical user.
Review quarterly. Audit custom roles to ensure permissions still match your team's needs.
Test before assigning widely. Create the role, assign it to yourself temporarily, and verify the permissions work as expected.

Custom Roles: Defining Granular Permissions