Permissions & Authorization Guide

This skill helps you work with Lightdash's CASL-based permissions system, including scopes, custom roles, and authorization enforcement.

What do you need help with?

1. Add a new scope/permission - Step-by-step guide to add a new permission
2. Debug a permission issue - Troubleshoot why a user can't access something
3. Understand the permission flow - Learn how permissions work end-to-end
4. Work with custom roles - Create or modify custom roles with specific scopes

Quick Reference

Key Files

Common Patterns

Backend permission check (services take account: RegisteredAccount and build the ability via this.createAuditedAbility(account) — raw user.ability is legacy, see docs/account-patterns.md):

import { subject } from '@casl/ability';
import { ForbiddenError } from '@lightdash/common';

const ability = this.createAuditedAbility(account);
if (ability.cannot('manage', subject('Dashboard', { organizationUuid, projectUuid }))) {
    throw new ForbiddenError('You do not have permission');
}

CASL Subject Scoping: Resource, Not Actor

CASL actor is passed before the check:

getUserAbilityBuilder({
    user: lightdashUser, // actor
    projectProfiles,
    permissionsConfig,
});

const ability = this.createAuditedAbility(accountOrUser); // actor

subject(...) must describe only the target resource:

ability.can(
    'manage',
    subject('X', {
        organizationUuid: target.organizationUuid,
        projectUuid: target.projectUuid,
    }),
);

Never fill subject(...) from actor fields like user.organizationUuid. Org-level grants may only check organizationUuid, so actor-sourced subject fields can become cross-org access on multi-org instances. Single-org dev hides it.

Frontend permission check:

const { user } = useApp();

if (user.data?.ability.can('manage', 'Dashboard')) {
    return <EditButton />;
}

or wrap in a CASL component:

import { Can } from '../../providers/Ability';

<Can I="manage" a="Dashboard">
    <EditButton />
</Can>

Full Documentation

For comprehensive documentation, read: .context/PERMISSIONS.md

This includes:

• Architecture diagram showing the complete permission flow
• All scope groups and modifiers (@self, @public, @space, etc.)
• Database schema for custom roles
• Step-by-step guide to add new scopes
• Troubleshooting guide

Adding a New Scope (Quick Guide)

You must update ALL the relevant ability layers:

1. Add subject (if new) to CaslSubjectNames in packages/common/src/authorization/types.ts

1. Define scope in packages/common/src/authorization/scopes.ts:

{
    name: 'manage:NewFeature',
    description: 'Description for custom role UI',
    isEnterprise: false,
    group: ScopeGroup.PROJECT_MANAGEMENT,
    getConditions: (context) => [addUuidCondition(context)],
}

1. Update project-level abilities in packages/common/src/authorization/projectMemberAbility.ts — add to the appropriate system role function (e.g., developer, admin)

1. Update org-level abilities in packages/common/src/authorization/organizationMemberAbility.ts if needed — note: org-level abilities are additive and cannot be restricted by project-level custom roles

1. Add to system role in BASEROLESCOPES in packages/common/src/authorization/roleToScopeMapping.ts (must stay in sync with projectMemberAbility.ts — the parity test roleToScopeParity.test.ts enforces this)

1. Update service accounts in packages/common/src/authorization/serviceAccountAbility.ts — add to ORG_ADMIN (or other service account scopes) if service accounts need this permission. Forgetting this breaks CI/CD pipelines.

1. Enforce in service via this.createAuditedAbility(account) + ability.cannot() — never raw user.ability (legacy pattern, see docs/account-patterns.md)

1. Add frontend check with useApp() → user.data?.ability.can()

Changing the Scope Vocabulary (Migrating Custom Roles)

Custom roles persist scope names as strings in the scopedroles table (roleuuid, scopename, grantedby). They are decoupled from system roles and do not auto-update when the scope vocabulary changes. Any rename / split / merge / removal must include a Knex migration that reconciles existing rows, otherwise self-hosted instances silently lose or retain permissions.

Before merging a scope change, evaluate the impact and write a migration:

Migration conventions (see packages/backend/src/database/CLAUDE.md for general safe-migration rules):

• Wrap the body in try/catch and log a recoverable manual-fix command on failure. These backfills are best-effort cleanup — failing them should never block subsequent migrations.
• Use ON CONFLICT DO NOTHING for inserts since (roleuuid, scopename) is the natural unique key.
• Preserve granted_by from the source row when copying a scope, so audit history points back at the original grantor rather than NULL.
• Provide a sensible down() — usually deleting the rows the up() inserted. If the change is irreversible (legacy cleanup), document why down() is a no-op.

Checklist when changing the scope vocabulary:

1. Determine which change type applies (rename / split / merge / remove / add / tighten).
2. If a migration is required, create it with pnpm -F backend create-migration <name> and follow the patterns above.
3. Update roleToScopeMapping.ts so system roles reflect the new vocabulary, and run the parity test.
4. Call this out in the PR description so reviewers can verify the data migration matches the code change.

Debugging Permission Issues

When a user gets "ForbiddenError":

1. Check scope exists - Is the scope defined in scopes.ts?
2. Check role assignment - Does the user's role include this scope?
3. Check conditions - Do the CASL conditions match the resource?
4. Check enterprise flag - Is isEnterprise: true but deployment isn't enterprise?
5. Check subject name - Case-sensitive match in CaslSubjectNames?

Use grep to find where the permission is checked:

grep -r "ability.cannot.*'manage'.*'YourSubject'" packages/backend/src/services/

Please describe what you're trying to accomplish, or ask me to explain any aspect of the permissions system.

Dashboard direct grants — the boundary rule

Direct grants let a user be shared a dashboard and gain access to the charts that dashboard owns, without being a member of the space the dashboard lives in. This is enforced through the CASL access array, not through special rules, and is gated behind the direct-access feature flag (off → behaves exactly like a plain space check).

The rule: a direct grant authorizes operations whose effect stays inside the owning dashboard. Anything that reads, moves, or copies content beyond the dashboard requires real space access.

It turns on one distinction:

• A chart owned by a dashboard (savedqueries.dashboarduuid set, space_id null) inherits the dashboard's grants — sharing the dashboard shares its own charts.
• A chart that merely lives in a space (space_id set) is governed by space access only — sharing a dashboard that references it grants nothing over it.

Why: the grant means "you may work within this dashboard", so it must never become a lever to read a chart's private space or relocate content into a space the granter never saw.

The single choke point is SpacePermissionService.getDashboardAccessContext(userUuid, { uuid, spaceUuid }) — read its doc comment before touching any grant call site. It returns the space context plus the requester's grants appended as access rows tagged grantedVia: 'dashboard'.

When you add or change a chart/dashboard access check:

• Owned-chart read/edit/create/delete that stays inside the dashboard → call getDashboardAccessContext with the chart's owning dashboardUuid.
• Boundary-crossing op (move to space, promote, content-as-code, pin, copy into a different dashboard) → pass uuid: null (or use getSpaceAccessContext) so grants never count. The expectNoGrantRows test tripwire guards these — if you route a boundary op through a grant, that test fails.
• Never resolve a grant against a spaceUuid the granting dashboard does not belong to; the helper asserts this pairing.

The write-vs-boundary split lives in SavedChartService (grant-aware: update, createVersion, create, delete, softDelete, duplicate; space-only: moveToSpace, the move half of updateMultiple, pinning). See also packages/backend/src/services/SpaceService/CLAUDE.md.