Skip to main content

RBAC Overview

RBAC stands for Role-Based Access Control. It is the system that decides what every member, app, and integration is allowed to do inside your workspace.

This page explains the core ideas. Once you understand them, the rest of the RBAC module — dashboard, roles list, permission checker — will feel familiar.

The four ideas​

1. Actor​

An actor is anyone or anything that performs actions. The RBAC contract recognizes the following actor types (see modules/rbac/specs/02-domain-model.md, Actor Representation):

Actor type (enum)Who it is
USERA real person signed in to the workspace
BOTAn automated bot account (e.g. a workflow runner or scheduled job)
INTEGRATIONA third-party application or service granted programmatic access
DELEGATED_AGENTAn agent acting on behalf of another actor (delegated/consent-scoped access)
GROUPA group identifier used for inherited permission checks (resolved through the groups service)

Every action in the workspace is recorded against the actor that performed it.

The Agents page (/rbac/agents) lists the first four types (USER, BOT, INTEGRATION, DELEGATED_AGENT). GROUP is part of the domain model so that group-scoped assignments resolve correctly during permission checks; it does not appear as a selectable filter on the Permission Checker or Assignments dropdowns.

2. Role​

A role is a named bundle of permissions — for example "Project Manager" or "Read-only Auditor". Instead of granting each permission individually, you assign a role to an actor and they inherit everything the role can do.

Roles come in two flavors:

  • System roles — shipped with the workspace, cannot be deleted (e.g. Owner, Admin, Member, Viewer).
  • Custom roles — created by your workspace administrators to match how your team works.

3. Permission​

A permission is a single thing an actor is allowed to do, written as resource:action — for example project:read, role:create, member:invite.

You don't usually grant permissions one at a time. You build (or use) a role, and the role carries the permissions.

4. Assignment​

An assignment connects an actor to a role inside a particular workspace. Assignments can also be scoped — for example, a user might be an Admin in one project but only a Viewer in another.

How a permission check works​

When you click a button or open a page, the workspace asks RBAC: "Is this actor allowed to do this action on this resource right now?"

RBAC answers by combining several signals:

  1. The roles the actor is assigned in this workspace.
  2. Any per-actor or per-role overrides (explicit grants or denials).
  3. Ownership rules (some resources auto-grant their creator).
  4. Workspace policies (e.g. external members may have additional restrictions).

RBAC runs the implemented 8-step evaluator in a fixed order and returns the first match (see modules/rbac/specs/05-workflows.md for the full sequence and decision paths):

  1. Actor-level deny — an explicit deny override on this actor ends the check immediately.
  2. Actor-level grant — an explicit grant override on this actor allows access (even if a role they hold would later deny).
  3. Role-level deny — a deny override attached to any role the actor holds wins over a role-level grant.
  4. Resource owner allow — for resources that auto-allow their creator (only checked when a resourceId is present).
  5. Role-level grant — an explicit grant override attached to any role the actor holds.
  6. Role default permission — the action default attached to the highest-priority role the actor holds (resolved via ActionDefinition). This is the most common "yes" path: it is how a Workspace Admin / Editor / Viewer assignment maps to allowed actions without any per-actor or per-role override existing.
  7. OPA policy evaluation (optional, controlled by OPA_ENABLED) — policy bundles can deny based on context like time-of-day, IP, workflow state. When enabled, every policy must allow for this step to pass.
  8. Default deny — if nothing matched, the answer is deny (safe fallback).

The shorthand "denials win" is true within a layer (actor or role) but is not a blanket rule across layers — an actor-level grant can allow access even when a role-level deny exists, and an OPA policy can still deny something all earlier steps would have allowed.

You can preview this evaluation yourself on the Permission Checker page.

Visibility — a separate concept​

RBAC answers "can the actor perform this action?". Visibility answers a different question: "can the actor even see that this resource exists?"

Visibility is configured on a per-resource basis (/rbac/visibility) with a priority-ordered set of rules. Five built-in visibility types — PUBLIC, PRIVATE, ROLE, GROUP, and CUSTOM — control discoverability without changing what RBAC allows on the resource itself. A resource can be visible to a teammate who is still denied an action on it, or invisible to someone who would otherwise have full RBAC access. See the Visibility page.

Resources, action definitions, and policies​

The Permission Checker (and the evaluator) reason about three more building blocks you can inspect in the UI:

  • Resources — concrete instances (e.g. project proj-123) registered with RBAC so they can be owned, scoped, or referenced by visibility rules. Listed on /rbac/resources and visualized on /rbac/resources/tree.
  • Action definitions — for each resource type (e.g. project), the set of recognized actions (read, update, delete, share, ...) plus the per-role defaults (Viewer / Editor / Admin). Browsable on /rbac/resources/types. These are what Step 6 of the evaluator consults.
  • Policy references — pointers to OPA bundles consulted by Step 7 (only when OPA_ENABLED is on at the service level).

What RBAC is not​

  • Not a billing tool. Quotas and seat counts are tracked separately.
  • Not a workspace activity feed. RBAC writes its own change log and permission-check audit log (visible on /rbac/analytics/audit); generic workspace activity (file uploads, project edits, etc.) lives in the workspace activity surfaces.
  • Not a tenant-level admin. Cross-workspace, platform-wide settings live in the global / platform admin area (the rbac service), not in this workspace-scoped module.

Where to go next​