Custom Roles

Custom roles allow you to create granular permission sets tailored to your organization’s specific needs. With custom roles, you can define exactly which scopes (permissions) users should have, giving you fine-grained control over access to Lightdash features and resources.

Cloud Enterprise

Custom roles are only available on Lightdash Enterprise plans.

For more information on our plans, visit our pricing page.

Overview

Lightdash provides two types of roles:

• System roles: Pre-defined roles (like Admin, Developer, Viewer) with a standard set of scopes. For more information about what these roles can do, check our default system roles permission matrix.
• Custom roles: User-defined roles where you can select specific scopes to match your exact requirements

Custom roles are created at the organization level but are assigned to users or groups at the project level, allowing you to control access on a per-project basis.

Custom roles can only add permissions, not remove them. Lightdash uses an additive permission model. If a user already has a permission granted through their organization-level role, a custom project role cannot take it away. Toggling off a scope in a custom role has no effect for users who already have that scope from their org role.

How additive permissions work

Custom roles operate at the project level and can only grant additional permissions on top of what the user’s organization role already provides. They cannot restrict or override org-level permissions.

For example, Organization Editors, Developers, and Interactive Viewers all have the “Manage Google Sheets” permission by default. If you create a custom project role with “Manage Google Sheets” toggled off, users with any of those org roles will still be able to export to Google Sheets because the permission comes from their org-level assignment.

Restricting permissions with custom roles

To use custom roles to restrict what users can do in a specific project, you need to start from a lower org-level role:

1. Downgrade users to Organization Viewer or Organization Member. Neither of these roles includes permissions like Google Sheets export, explore access, or scheduled deliveries.
2. Create a custom project role with only the specific permissions you want to grant (e.g., explore data, view dashboards, schedule Slack/email deliveries).
3. Assign the custom role to those users or groups at the project level.

This approach gives you precise control over what users can do in each project without granting broad permissions through the org role.

Check the organization roles permission matrix to see which permissions each org role includes. Choose the lowest org role that meets your baseline needs, then use custom project roles to layer on additional access.

Creating Custom Roles

Access Custom Roles Settings

1. Navigate to Settings → General Settings → Custom Roles
2. You’ll see a list of existing custom roles in your organization

Create a New Role from Scratch

1. Click Create New Role
2. Enter a Role Name (e.g., “Marketing Analyst”, “Finance Viewer”)
3. Add an optional Description to explain the role’s purpose
4. Select the specific scopes (permissions) you want to include:
   • View permissions: Allow users to see content (dashboards, charts, spaces)
   • Create permissions: Allow users to create new content
   • Manage permissions: Allow users to edit, delete, or administer content
5. Click Save to create the role

Duplicate an Existing Role

If you want to create a role similar to an existing one:

1. Find the role you want to duplicate (system role or custom role)
2. Click the ⋯ menu next to the role
3. Select Duplicate Role
4. Enter a new name for the duplicated role
5. Modify the scopes as needed
6. Click Save

This is particularly useful when you want to create a role similar to a system role but with some modifications.

Assigning Custom Roles

Custom roles are assigned at the project level to provide granular access control:

Assign to Users

1. Go to Project Settings → Access
2. Find the user you want to assign a role to
3. Select the custom role from the dropdown
4. The user will now have the permissions defined in that custom role for this project

Assign to Groups

1. Go to Project Settings → Access
2. Find the group you want to assign a role to
3. Select the custom role from the dropdown
4. All members of the group will inherit the custom role permissions for this project

Scope reference

Manage SQL Runner vs Manage Custom SQL

These two scopes are independent and control different features.

Manage SQL Runner controls access to the SQL Runner, which lets users write and run ad-hoc SQL queries directly against your data warehouse. It also controls the ability to create virtual views and write back dbt models from SQL Runner queries.

Manage Custom SQL controls the ability to create custom SQL dimensions inside the Explore view. Custom SQL dimensions let users add calculated fields to an existing table using raw SQL. This scope does not grant access to the SQL Runner.

If you want a user to query tables that include custom SQL dimensions created by others, they don’t need either of these scopes. Any user with access to the Explore view can use existing custom SQL dimensions in their queries - these scopes only control who can create them.

Troubleshooting

Custom role doesn’t restrict a permission (e.g., Google Sheets export)

Custom roles can only add permissions—they cannot remove permissions granted by the user’s organization role. If you toggled off a scope in a custom role but the user still has access, their org role is granting that permission.

To fix this: Downgrade the user’s org role to Viewer or Member, then use a custom project role to grant only the specific permissions they need. See Restricting permissions with custom roles above.

Users can’t see expected content

• Verify the custom role includes the necessary view scopes
• Check that the role is assigned at the project level where the content exists
• Remember that organization-level permissions may override custom role limitations

Role Changes Not Taking Effect

• Users may need to refresh the page for role changes to take effect
• Verify the role was saved successfully and assigned to the correct users/groups

Managing Existing Custom Roles

Edit a Custom Role

1. Go to Settings → General Settings → Custom Roles
2. Click on the role you want to edit
3. Modify the name, description, or scopes
4. Click Save - changes will apply to all users and groups assigned this role

Delete a Custom Role

1. First, ensure no users or groups are assigned this role
2. Go to Settings → General Settings → Custom Roles
3. Click the trash icon next to the role
4. Confirm the deletion

Deleting Roles: Once deleted, a custom role cannot be recovered. You can’t remove a role that is currently assinged to users or groups.

Custom roles provide powerful flexibility in managing access to your Lightdash organization. By carefully designing roles that match your team’s responsibilities and workflows, you can ensure users have exactly the permissions they need while maintaining security and organization.