From d7c05d901a848105cdd60b9b57348b209c8bcb7a Mon Sep 17 00:00:00 2001 From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com> Date: Fri, 27 Mar 2026 17:01:28 +0000 Subject: [PATCH] Clarify that custom roles can only add permissions, not remove them Generated-By: mintlify-agent --- references/workspace/custom-roles.mdx | 34 +++++++++++++++++++++++---- 1 file changed, 30 insertions(+), 4 deletions(-) diff --git a/references/workspace/custom-roles.mdx b/references/workspace/custom-roles.mdx index f621a399..0ff24024 100644 --- a/references/workspace/custom-roles.mdx +++ b/references/workspace/custom-roles.mdx @@ -24,9 +24,29 @@ Lightdash provides two types of roles: 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. - - **Additive Permissions**: Lightdash uses an additive permission model. If a user already has a scope granted through their organization-level role, assigning a custom role will not restrict that access. Custom roles can only add permissions, not remove existing ones. - + + **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](/references/workspace/roles#organization-roles) 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 @@ -97,7 +117,13 @@ These two scopes are independent and control different features. ## Troubleshooting -### Users Can't See Expected Content +### 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](#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