Custom Roles

​

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.

​

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.

​

Troubleshooting

​

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

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.