Roles, grants, and policies

LeapView authorization assigns privileges on securable resources to principals, service principals, and groups. Authentication and provisioning establish identities; the grant engine determines what those identities may do.

Securable resources

Securable objects include the server-bound Project, dashboards, semantic models, sources, Models, datasets, tables, and columns. Project-wide role assignments and exact resource grants can both contribute authority, but repository paths, graph dependencies, and descriptive ownership do not confer privileges. The server binding does not provide Project enumeration or request-time Project switching.

The portable source graph has exactly six source-root kinds: connection, source, model, semantic_model, pipeline, and dashboard. Groups, role bindings, grants, data policies, and dashboard-publication declarations are target policy or publication inputs compiled into authorization and publication snapshots; they are not additional source-root catalog nodes.

Review the effective privilege result rather than assuming a direct binding is the only source of access. The Current User and Access APIs expose effective-privilege views for this purpose.

Project roles

Project role bindings apply the typed presets viewer, explorer, editor, project admin, publisher, release approver, release operator, and auditor. Bind a stable group wherever access follows team membership. Role bindings are administered on the target through Admin → Access, identity detail pages, or the Access API; they are not files in the analytics source root.

An editor can discover governed semantic data and read, create, or update the authored resources covered by its typed action expansion and targets. Catalog and Develop navigation depend on the caller's effective permissions on those resources. The editor preset does not include publication, deletion, sharing, Pipeline execution, release, or administration authority.

Roles express common responsibilities. Their typed catalog expansions are reviewable action lists, not an implicit bypass around resource targets, credential attenuation, prerequisites, or data policies. Keep project administration and sharing authority limited. Use dedicated publisher, release approver, and release operator identities for their corresponding release responsibilities.

Admin approval and activation

An authenticated access manager can approve a typed project-role assignment within their current permission and credential ceiling. The grant and its approval are audited together and become effective on the next request, without a separate analytics release. A pending assignment exposes Approve access on the user, group, or service-account detail page; this repeats the same grant checks before making it active.

A user cannot approve their own access merely by requesting it. Approval requires project.access.manage, delegation authority, and every permission being assigned. A scoped API credential must also contain those permissions. The Project Admin preset continues to describe access administration; it does not implicitly include every data, Pipeline run, deletion, or platform permission. An unapproved staged request cannot overwrite an already approved assignment. Role API responses expose the server-owned adminApproved marker so clients can verify the complete policy identity; creation requests cannot set it.

Existing assignments are not automatically marked approved during upgrade. Bootstrap and unapproved staged assignments still wait for a qualified release. Revocations remain immediate. Live role approval retains the current serving graph and its row/column policies; it cannot publish new data or activate a staged resource grant.

Explicit grants

Use a target-owned grant when one subject needs one privilege on a specific securable object outside the standard role shape. Create and review explicit resource grants through the Access API, using the exact compiled resource ID and the narrowest supported privilege. Admin → Access provides role assignment controls and the permission catalog; it does not provide an explicit resource-grant editor.

Choose the narrowest object and privilege that supports the task. Avoid accumulating one-off direct user grants; they are harder to review and can survive team changes.

Typed action-target permissions

The typed permission profile is leapview.permissions/v1. A credential or assignment carries individual action-target pairs, preserving which operation is allowed on which audience. Do not model a credential as one list of actions plus another list of resources; that representation can accidentally authorize every combination of the two lists.

An exact resource target includes the bound Project, resource kind, and resource ID. Project-scoped actions include the Project but no resource ID; creation actions use this scope because their resource does not exist yet. A future-resource selection is explicit with a Project target, a resource kind, and includeFuture: true. Without that flag, a current selection is retained as exact resource pairs and does not automatically cover resources created later. Instance-scoped platform actions name the instance and are separate from Project administration.

Named roles and workflow presets are presentation conveniences over their expanded typed actions. Review the expansion and every target before granting it. PROJECT_ADMIN does not imply platform administration; platform actions require their own instance audience and the principal's durable platform authority. See the generated typed permission catalog for the current profile, actions, prerequisites, and role expansions.

Personal token settings receive only exact, already-authorized action-target pairs from the active authorization snapshot. The current migration projection is deliberately limited to qualified dashboard consumption and exact Pipeline execution; it never expands broad legacy Project roles into operational, administrative, sharing, publication, or platform actions. An unavailable or unproven typed option set fails closed. Legacy capability rows remain a bounded migration and bootstrap concern, not a public issuance input.

Data policies

Data policies constrain analytical access beyond navigation or query permission. A row-filter policy limits eligible records; a column-mask policy changes exposure of a protected column. Policies target a securable object and may target a subject.

Policy expressions are part of the governed server query boundary. Apply them consistently to browser dashboards, headless API queries, agent tools, preview, and other data surfaces. Do not rely on hiding a dashboard component or browser column as a security control.

Test policies with representative users, including aggregates. Row filtering can change totals, distinct counts, relationship behavior, and whether an empty result is expected. Column masking must preserve safe types and must not leak the raw value through labels, tooltips, exports, or alternative datasets.

Policy composition

LeapView composes every applicable policy before planning a raw, aggregate, spatial, or multi-dataset query. The composition rules are independent of query surface and repository traversal order:

Within one row-policy expression, entries in filters are also ANDed. Use separate subject policies to express alternative entitlements; do not encode authorization alternatives in reader-controlled dashboard filters. allowAll is explicit so an empty or malformed expression cannot accidentally broaden access.

Policy IDs remain part of the effective-policy fingerprint and query audit identity. Composition errors name the relevant IDs, allowing an administrator to resolve contradictory masks without relying on policy load order.

Policy expressions are compiled into a typed form during project validation, serving-state snapshot assembly, or an audited API write. Invalid operators, empty filters, ambiguous expression forms, and unsupported masks reject that boundary before it becomes active. Existing stored policies are compiled when first loaded and cached by their exact type and expression; an invalid stored policy fails closed instead of reaching a query planner.

Owners and administration

Ownership and platform administration are distinct from ordinary project-resource use. Keep the instance-wide platform_admin role, project PROJECT_ADMIN, and resource capabilities such as RESOURCE_USE, RESOURCE_READ, RESOURCE_EDIT, RESOURCE_MANAGE, RESOURCE_SHARE, and RESOURCE_PUBLISH separated according to operational responsibility.

A service principal used by CI should exist only on the target instances and receive the project and deployment/data privileges required by that pipeline. A read-only integration should not inherit project activation or grant management.

Review access

Use this periodic review:

1. List active principals, service principals, and groups.
2. Reconcile SCIM membership and local groups.
3. Inspect effective privileges for sensitive project resources.
4. Find direct grants that duplicate or exceed role access.
5. Review owner, admin, deployer, and grant-manager assignments.
6. Review data policies against current semantic fields.
7. Remove or deactivate obsolete identities and revoke credentials.
8. Audit every binding, policy, and ownership change.

Validate target access policy before deployment and test with a non-owner principal afterward. Use the Access API and the effective-privilege views to review role bindings, grants, and data policies.