Documentation / Administration

Roles & Permissions (RBAC)

The definitive guide to Nexus access control — tenant roles, per-resource scoped grants for both users and app principals, the create/update/delete permission split, admin edit-locks, and effective-permissions evaluation.

This is the definitive reference for access control in Nexus by Stingray. Nexus enforces granular, per-resource role-based access control (RBAC) over every resource in your tenant — data connections (bridges), reports, pipelines, collections, files, tools, and Sites — and the same engine governs interactive users and connected automation (API keys and OAuth apps). One permission policy covers your whole platform, including AI agents on the embedded MCP server. This page is for administrators designing access policy for a Nexus deployment that runs inside their own Azure tenant.

The three layers

Permissions in Nexus are composed from three layers. Most teams use only the first; the second and third exist for least-privilege and delegated automation.

Roles and bundles — A role is a named set of fine-grained permissions (for example report:read, pipeline:execute, bridge:use, admin:rbac). Nexus ships ready-made bundles so you can grant common access without hand-composing permissions.
Per-resource scoped grants — Any grant can be narrowed to specific named resources, enforced on every request that targets a single resource.
Execution roles — An admin can pin a curated role to a single pipeline or report, letting a low-privilege caller run a trusted resource without holding standing elevation. This layer has its own page.

Tenant roles (the bundles)

Every member holds a tenant-level baseline role. Nexus ships two built-in roles — Reader and Admin:

Role	Intended for	Can read	Can author (create/update)	Can run	Can administer
Reader	Analysts, viewers, dashboards	Reports, pipelines, files, sites, history/diffs	No	Runs a report/pipeline only where separately granted	No
Admin	Platform owners	Everything	Everything	Everything	RBAC, bridges, execution-role bindings, restores

Reader is deliberately read-first: it includes reading version history and diffs, but not restoring, authoring, or managing. Admin is the only role that can grant permissions, manage service bridges, bind execution roles, and perform write-level restores. There is no built-in "Author" or "Developer" role. For anything between pure-read and full-admin — for example, a builder who can create and change reports or pipelines within a scope but cannot manage identity or RBAC — build a custom role from individual permissions (via uql_create_role) and combine it with per-resource scoped grants and, where a trusted resource must run without standing elevation, execution roles.

Bundles are a starting point, not a straitjacket. You can build custom roles from individual permissions when a bundle is too broad — the common case being a narrow role you attach as an execution role or hand to a single-purpose integration.

Per-resource scoped grants

A grant can be unscoped (it applies to any resource of that type) or scoped to an explicit list. A scope is a small JSON object naming the resources the grant covers, with "*" meaning all of that type:

{
  "pipelines":   [142, 187],
  "reports":     ["*"],
  "collections": [9],
  "bridges":     ["finance-sql"],
  "sites":       ["ops-portal"],
  "tools":       ["lookup-customer"]
}

With this grant, the principal can act on pipelines 142 and 187, every report, collection 9, the finance-sql connection, the ops-portal Site, and the lookup-customer tool — and nothing else. Every route that targets a single resource (a specific pipeline, report, connection, collection, site, or tool) checks the request against the scope before acting. A broad principal such as Reader or Admin passes any resource of the permitted type; a scoped principal is confined to its list, and a request for anything outside the list is denied.

Scoped grants are honored identically for users and for apps. You can hand an integration an API key that can run exactly one report and reach exactly one data connection — nothing else is visible or callable, even by crafting a request. Collections deserve special mention: on data execution the target collection is included in the entitlement check, so a collection-scoped grant genuinely confines which data a principal can touch, not just which report objects it can open.

The create / update / delete permission split

Nexus does not treat "write" as a single bit. Authoring permissions are split by verb, so you can grant the ability to create new resources without the ability to change or remove existing ones — or vice versa:

Verb	Permission shape	Grants the ability to
Create	`<kind>:create`	Add new resources of a kind
Update	`<kind>:update`	Modify existing resources (subject to scope)
Delete	`<kind>:delete`	Remove resources (subject to scope)
Execute	`<kind>:execute` / `:run`	Run a pipeline or report
Read	`<kind>:read`	View definitions, results, history, diffs

This split lets you express real-world policy precisely. For example, a build pipeline's API key might hold report:create + report:update scoped to a reporting namespace but never report:delete, so automation can publish and revise reports but can never destroy one. The same split governs the MCP tool surface: an agent that may create a resource is not thereby allowed to delete it.

App principals are first-class

API keys and OAuth applications are full RBAC principals, not a side channel. When you register or update an app you assign it roles (and optional scopes), and those roles govern everything it can do through the Nexus REST API and the MCP surface. Key properties:

Same engine, no weaker path. An app is evaluated by the identical permission check as a user. There is no "machine mode" that relaxes the rules.
Independent lifecycle. Revoking an app or rotating its secret cuts its access immediately, without touching any human account. Removing an app revokes its access in the same operation.
Run-as semantics for user-delegated tokens. A personal access token runs as the issuing user and is bounded by that user's permissions — it is not a root credential. App-registration (client-credentials) tokens carry only the app's own assigned roles.

Because automation is bound by the same RBAC policy as people, the audit trail treats a machine action the same as a human one: identity → permission check → action → record.

Admin edit-locks

Some bindings are security boundaries and must not be quietly rewritten by the person they constrain. Nexus enforces admin edit-locks on those:

Setting or changing a resource's execution role is administrator-only.
Once a pipeline or report carries an execution role, updating or deleting that resource also becomes administrator-only — so a non-admin author cannot point a curated privileged role at a pipeline and then rewrite the pipeline's code.
Managing service bridges and RBAC grants themselves is administrator-only.

The edit-lock keeps the role-to-resource binding tamper-resistant: the curated, admin-controlled role stays the boundary, and the author who runs under it cannot expand what it does. See Execution Roles for the full model.

Effective permissions

Because grants stack — a baseline role, plus additional roles, plus scopes, plus a possible execution role on a specific resource — administrators need a way to answer "what can this principal actually do right now?" without reasoning it out by hand. Nexus computes effective permissions: the resolved set for a given user or app, showing which permissions apply and how scopes narrow them. Use it to:

Verify that a new hire or contractor is as constrained as you intended before they start.
Audit an application key before handing it to an integration partner.
Confirm that removing a role actually dropped the access you expected.

The evaluation is deny-by-default: a principal can do only what a matching grant explicitly allows, scoped to resources the grant names. A missing grant is a denial, not a fallthrough.

Worked patterns

Read-only analyst. Grant the Reader bundle, scoped to the reports and collections they need. They view results and read history, but cannot author, restore, or run pipelines they were not separately granted.
Single-purpose integration. Register an app; assign a custom role holding report:execute scoped to one report and bridge:use scoped to one connection; rotate its key on a schedule. It can do exactly one job.
Publisher without deleter. Give a CI app report:create + report:update scoped to a namespace, but omit report:delete. It ships and revises, never destroys.
Curated privileged report. Build a tightly scoped role, attach it as the execution role on a finance report, and let analysts run it with assume_role: true while their everyday permissions stay low. The edit-lock keeps the report tamper-resistant.

Limits & guarantees

Deny by default. No grant means no access. Scopes only ever narrow; they never widen a role beyond its permissions.
One engine for everyone. Users, API keys, OAuth apps, and MCP agents are all evaluated by the same check. Agents act strictly within the connecting identity's permissions.
Enforced per request, per resource. Scoped grants are checked on every route that targets a single resource, including data execution against a collection — not just at login.
Admin-gated boundaries. RBAC changes, service-bridge management, execution-role bindings, and write-level restores are administrator-only, and locked resources cannot be edited around.
Runs inside your tenant. All of this executes in your own Azure subscription; no policy decision leaves your boundary.