Roles & Permissions

A role is a named bundle of permissions. A role assignment grants a user a role at one of three scopes (global / org / process-group). Permissions are the atomic units the engine checks; roles exist so a UI and an admin don’t have to enumerate dozens of permissions per user.

Conduit ships eight global built-in roles. Each org can also create custom roles drawn from the same permission catalog.

The eight built-in roles

All are seeded in migrations/021_roles.sql and authoritative — change the migration (or add a new one) to add or modify a built-in.

PlatformAdmin

Holds every permission in the catalog. Granted only at global scope, never inside an org. Bypasses org membership checks. The bootstrap admin is created with this role.

OrgOwner

Everything an org needs to operate, minus the user-identity verbs (user.create, user.update, user.delete) which require a global admin since they affect the global identity table. 51 of 55 permissions.

OrgAdmin

Pure administration: manage memberships, roles, auth configuration, and API keys. No process / instance / decision / secret powers — pair this with Developer or Operator if the same person needs both kinds of access.

Developer

Full process and decision lifecycle: design, deploy, run, monitor, cancel. Can manage process groups and secret metadata (not plaintexts). 29 permissions.

Operator

Run and monitor: start / cancel / pause / resume instances, complete tasks, correlate messages, broadcast signals. Read-only on designs (cannot author or deploy). 15 permissions.

Modeller

Design BPMN and DMN drafts: create and edit processes, decisions, and process groups. Cannot deploy or promote, cannot run instances. 13 permissions.

Reader

Every *.read* permission. Useful for analysts and auditors who need full visibility but no write access.

Worker

Service account for external task execution: external_task.execute, plus process.read and decision.read to fetch metadata. Pair with an API key to authenticate workers.

Custom roles

Each org can define its own roles drawn from the same permission catalog.

POST /api/v1/orgs/{org_id}/roles
Authorization: Bearer …
Content-Type: application/json

{
  "name": "QA Analyst",
  "permissions": [
    "process.read",
    "decision.read",
    "instance.read",
    "instance.start",
    "task.read"
  ]
}

• Names are unique within an org.
• Permissions are validated against the catalog at insert time (the role_permissions.permission CHECK constraint enforces this at the database level).
• Custom roles can be assigned at any scope where their permissions are eligible — for example a role containing only PG-scopable permissions can be granted at PG scope; a role mixing org-only and PG-scopable permissions can only be granted at org scope.

Required permission: role.create. Use PATCH /api/v1/orgs/{org_id}/roles/{id} to modify, DELETE to remove. Editing a role’s permissions takes effect on the next request — there is no need to re-issue tokens.

The full permission catalog (55 permissions)

Permissions are dotted strings of the shape domain.verb. The CRUD verbs (create, read, update, delete) are used wherever authorization aligns with database operations. Domain verbs (e.g. process.deploy, secret.read_plaintext, external_task.execute) appear where authorization meaningfully diverges from CRUD — state transitions, metadata-vs-plaintext, designed-vs-promoted.

The “Scope” column shows where each permission may be granted:

• org — grantable at global or org scope.
• org+PG — also grantable at process-group scope, with grants cascading from org to every PG within it.
• global — grantable only globally (currently just org.create).

Organisation

Organisation membership

User identity (global)

Role definitions

Role assignments

Authentication configuration

Process definitions (BPMN)

Process groups

Process instances

User tasks

External (worker) tasks

Decisions (DMN)

Secrets

Secrets are org-only: they’re shared infrastructure for the org, not partitioned by process group.

API keys

Process layout

Business events

Why some permissions are org-only

Three categories of permission cannot be granted at PG scope:

1. Identity / administration — managing users, roles, role assignments, and auth config affects the whole org. Scoping these to a single PG would create incoherent slices (“this user can create roles but only roles usable in PG X”).
2. Org-wide infrastructure — secrets and API keys belong to the org, not a PG.
3. Cross-PG routing — message.correlate and signal.broadcast route to subscriptions across every PG in the org. Granting these per-PG would make their semantics confusing (which subscriptions can be hit?). See src/auth/permission.rs::is_pg_scopable.

Permission check in handlers

Every protected handler calls one of:

principal.require(Permission::ProcessRead)?;            // org-level only
principal.require_in_pg(Permission::ProcessRead, pg)?;  // org-or-PG-cascading

The second form succeeds if the permission is held at org scope or at the specific PG. See src/auth/principal.rs.

Cross-references

• How scope assignments combine: Scope Levels
• How users get into orgs: Users & Membership
• The catalog in code: src/auth/permission.rs, mirrored by migrations/021_roles.sql