Skip to content

Roles, Policies & Permissions (RBAC) ​

Overview ​

ODP uses a Role-Based Access Control (RBAC) model:

  • Roles — Group users and define system-level access flags.
  • Policies — Define granular read/write/delete permissions on specific collections and fields.
  • Permissions — Individual permission rules within a policy (collection + action + field restrictions + filter conditions).

Roles ​

Data Model ​

Table: odp_roles

ColumnTypeDescription
idUUIDPrimary key
namevarcharDisplay name
iconvarcharUI icon name
descriptiontextRole description
parentUUIDFK to odp_roles.id — role hierarchy (nullable)
admin_accessbooleanBypasses all permission checks
tech_accessbooleanSystem/debug access (implies admin_access)
app_accessbooleanCan access the app panel
impersonate_accessbooleanCan use impersonation endpoints
enforce_tfabooleanRequire TFA for users in this role (read at login — see note below)
protectedbooleanLocked default role (Administrator, Public) — cannot be deleted
shortnamevarchar(100)Slug of the role. Slugified on write; auto-generated from name on create when omitted
weightintegerEscalation ceiling — see Role Weight. Default 10; the seeded Administrator role is 100

Access Flag Hierarchy:

tech_access → admin_access (implied)
admin_access → bypasses all RBAC checks
app_access → can log into the app panel
impersonate_access → can impersonate other users

Role Endpoints ​

POST /roles ​

Create a role. Admin only.

Request Body

json
{
  "name": "Editor",
  "icon": "edit",
  "description": "Can create and edit content",
  "app_access": true,
  "admin_access": false,
  "tech_access": false,
  "weight": 20
}

weight defaults to 10 when omitted or null. The request is rejected with 403 if weight is above the caller's own role weight (see Role Weight).

Response 200

json
{ "data": "role-uuid" }

GET /roles ​

List all roles.

Auth required: Yes

Supports standard query system.


GET /roles/:id ​

Read a single role.


PATCH /roles/:id ​

Update a role. Admin only. Subject to the role weight guard: the caller cannot update a role that sits above their own weight, nor raise any role's weight above their own.


DELETE /roles/:id ​

Delete a role. Admin only. Subject to the role weight guard (a role above the caller's weight cannot be deleted).

A protected role (the seeded Administrator and Public roles) cannot be deleted — RolesService throws 422 UnprocessableContentError (src/services/roles.ts).


Role Weight ​

Every role has an integer weight. It is the escalation ceiling: an actor may only assign, create or manage roles (and users holding them) whose weight is less than or equal to the weight of the actor's own primary role (accountability.role). Source: service/api/src/permissions/role-weight.ts.

  • New roles get weight: 10 — the column default (migration 025-roles-shortname-weight.ts) and the RolesService.createOne default when the payload omits it or sends null.
  • The seeded Administrator role (protected: true + admin_access: true) is raised to 100 by migration 091-administrator-role-weight.ts, so no custom role at the default weight can grant or manage it.
  • An actor with no role — or a role id that no longer exists — has weight 0. A target role with no stored weight also counts as 0.

Applies to admins too

admin_access bypasses collection permissions, not the role hierarchy. A tenant admin on a role of weight 50 cannot hand out the Administrator role (100), reset an administrator's password, or edit the Administrator role.

Guarded operations ​

OperationRule (blocked when…)Error message
POST /rolespayload weight (or the default 10) > actor weightCannot set a role weight higher than your own role
PATCH /roles/:idpayload weight > actor weightCannot set a role weight higher than your own role
PATCH /roles/:id, DELETE /roles/:idthe target role's current weight > actor weightCannot manage a role with a higher weight than your own role
POST /users (single and batch create)the role being assigned has weight > actor weightCannot assign a role with a higher weight than your own role
PATCH /users/:id (and batch update)the target user's current role weight > actor weightCannot manage a user whose role has a higher weight than your own role
PATCH /users/:id with role in the payloadthe new role has weight > actor weightCannot assign a role with a higher weight than your own role
DELETE /users/:id (and batch delete)the target user's current role weight > actor weightCannot manage a user whose role has a higher weight than your own role
POST /users/invitethe invited role has weight > actor weightCannot assign a role with a higher weight than your own role
POST /users/:id/tfa/disablethe target user's current role weight > actor weightCannot manage a user whose role has a higher weight than your own role
DELETE /users/:id/providers/:linkId (unlink an SSO sign-in)the target user's current role weight > actor weightCannot manage a user whose role has a higher weight than your own role
POST /access, DELETE /access/:id (attach / detach a policy)the target user's role weight, or the target role's weight, > actor weightCannot manage a user whose role has a higher weight than your own role / Cannot manage a role with a higher weight than your own role
PATCH /settings with public_role / public_registration_rolethe new role has weight > actor weightCannot assign a role with a higher weight than your own role

Notes:

  • Equal weight is allowed (<=). Two roles at the same weight can manage each other.
  • The actor's own user row always passes the "manage user" check, so users can still update themselves. Changing your own role still goes through the "assign role" check.
  • Service accounts are users whose role has service_account: true, so creating or re-roling one goes through the same user checks.
  • null / empty role values in a payload are not checked (removing a role is not an escalation).
  • Deleting a protected role is refused separately with 422 (see DELETE /roles/:id), even when the weight check passes.

Not restricted — internal calls. When there is no accountability or no user on it (CLI, bootstrap, SSO provisioning, self-registration via POST /users/register), the guard is skipped: the role those flows assign is configured by an admin, not chosen by the caller.

No bypass through generic writes. The guard lives in RolesService / UsersService. Generic item writes cannot reach those tables with a plain ItemsService: the /items route rejects system (odp_*) collections, and the MCP items_* tools throw 403 ("<collection>" is a system collection — use its dedicated tool). The MCP roles_* / users_* tools use the dedicated services, so they are guarded.

Error response ​

A blocked call returns 403 with code FORBIDDEN:

json
{
  "errors": [
    {
      "message": "Cannot assign a role with a higher weight than your own role",
      "extensions": { "code": "FORBIDDEN" }
    }
  ]
}

Example ​

Actor role: Tenant Admin (admin_access: true, weight: 50).

bash
# OK — 30 <= 50
POST /roles
{ "name": "Editor", "app_access": true, "weight": 30 }

# 403 — "Cannot set a role weight higher than your own role"
PATCH /roles/editor-role-uuid
{ "weight": 80 }

# 403 — "Cannot assign a role with a higher weight than your own role"
#        (Administrator is weight 100)
PATCH /users/user-uuid
{ "role": "administrator-role-uuid" }

# 403 — "Cannot manage a user whose role has a higher weight than your own role"
#        (target user holds the Administrator role)
PATCH /users/admin-user-uuid
{ "password": "new-password" }

In the admin webapp, the role form (RoleFormModal.vue) exposes a Weight field, and the user role picker only lists roles whose weight is <= the current user's role weight (use-roles.ts), mirroring the backend guard.


Policies ​

Policies are named permission sets that can be attached to roles.

Data Model ​

Table: odp_policies

ColumnTypeDescription
idUUIDPrimary key
namevarcharPolicy name
iconvarcharUI icon
descriptiontextDescription
admin_accessbooleanPolicy grants admin access
app_accessbooleanPolicy grants app access
enforce_tfabooleanLegacy — no longer enforced. TFA enforcement moved to odp_roles.enforce_tfa (#44); the login flow reads the role, not the policy. This column is kept for backward compatibility but is not read.

Policy Endpoints ​

POST /policies ​

Create a policy. Admin only.

json
{
  "name": "Content Manager",
  "description": "Full access to content collections",
  "app_access": true
}

GET /policies ​

List all policies. Supports standard query system.


GET /policies/:id ​

Read a single policy (with its permissions nested).


PATCH /policies/:id ​

Update a policy. Admin only.


DELETE /policies/:id ​

Delete a policy. Admin only.


Permissions ​

Permissions define what a policy can do on a specific collection.

Data Model ​

Table: odp_permissions

ColumnTypeDescription
idintegerPrimary key
policyUUIDFK to odp_policies.id
collectionvarcharCollection name (e.g., articles)
actionvarcharcreate, read, update, delete, share
fieldsjsonArray of allowed field names (["*"] = all)
permissionsjsonFilter condition — limits which items are accessible
validationjsonZod-compatible validation rules for write operations
presetsjsonDefault field values applied on create

Permission Actions ​

ActionDescription
createInsert new items
readRead items (with optional row-level filter)
updateModify existing items
deleteRemove items
shareShare items publicly

Field-Level Permissions ​

The fields array controls which columns are returned/writable:

json
{ "fields": ["title", "status", "published_at"] }

Use ["*"] to allow all fields.

Stored formats (src/permissions/fetch-permissions.ts). fields is read as a JSON array, or as the legacy comma list title,body (a bare * = all fields). permissions and validation are read as a JSON object or null. POST/PATCH /permissions accept either form (a string is stored as it is) and refuse any other value with 400 INVALID_PAYLOAD naming the column. A stored value in no readable form (seed, migration, hand edit) makes the whole record grant nothing, and a warning names the record, its policy and the column. (Before, such a value read as null: every field, every row, or no validation.) An unreadable presets only drops the defaults.

Row-Level Permissions (Filter Conditions) ​

The permissions JSON uses the same filter syntax as query filters:

json
{
  "permissions": {
    "author_id": { "_eq": "$CURRENT_USER" }
  }
}

Where the permissions filter applies, by action (dynamic variables such as $CURRENT_USER are resolved in every case):

ActionWhat checks the rowFilter support
readprocessAst injects it into the query (src/permissions/process-ast.ts), at every relation levelFull query filter syntax, relational keys included
update, deleteItemsService.verifyRowAccess counts the target keys that match it before the write; any miss answers 403 and nothing is written (batches included)The same filter engine as read (applyFilter, src/database/ast/filter-parser.ts), relational keys included; fails closed (see below)
createNot applied: there is no stored row. Use validation to bound the payload—

A record with no permissions filter, or {}, allows every row.

Several records on one collection and action (from several policies) follow one model, the cases model: each record is a case, a filter plus a field list. A row is reachable when any record matches it, and a field shows on a row only when a record that grants the field matches that row.

ActionRowsFields
readOR of the records' filters, at every relation level, in relational filters and in meta counts and aggregatesPer row: field f shows where a record granting f matches the row. On the other rows it reads as null (the key is present, the value is null)
updateOR of the records' filters (ItemsService.verifyRowAccess)Per row: each payload field must be granted by a record that matches the target row, else 403 and nothing is written
deleteOR of the records' filters—
create— (no stored row)Union of the field lists (validateFieldAccess); every record's validation must pass (AND)

Example: a role holds A "own items" ({ "user_created": { "_eq": "$CURRENT_USER" } }, every field) and B "published items" ({ "status": { "_eq": "published" } }, fields id, title, status) on articles, the same two records for read and update.

  • It reads its own items plus every published one.
  • On a published item of another author, title and status show, and body is null.
  • It can update body on its own items only, and title on any row it reads.

A masked value is null for every predicate too: a filter, search, sort, groupBy or aggregate on a field sees null on the rows where the field is masked, so no query can tell the hidden value. A record without a filter (or {}) matches every row, so its fields show on every row. A single record behaves, and compiles to SQL, exactly as it did before this model.

Moving from the earlier AND model

Before this model, several read records combined with AND: a row had to match every record, and a second policy could only take rows away. Existing users therefore gain rows and lose nothing: every row they read before matched every record, so every field they saw is still shown there. On the rows they now gain, fields of records that do not match those rows are null.

Known cost on PostgreSQL

An aggregate or groupBy that reads a masked field runs over a derived table of the masked columns, and PostgreSQL then does not use a parallel aggregate. Measured on 1M rows: about 2.5–3× the unmasked aggregate (EXPLAIN ANALYZE), 5.6× at the harness p95 (service/api/test/perf/read-cases-results.md). MySQL is not affected (0.92×). Accepted 2026-11-03; a faster PostgreSQL form is in the backlog.

Update and delete filters fail closed

A filter means on update / delete what it means on read: every operator and relational path of the query filter syntax, with the same SQL. A write is refused (403, nothing written) when the filter cannot be applied as written:

  • an operator or field the filter engine refuses (_regex, an unknown operator, an unknown field);
  • a part that adds no condition: an empty _and / _or array, an empty element in it ({ "_or": [{}] }), a field with no operator ({ "status": {} }) or with a bare value ({ "status": "open" }).

A record whose whole filter is {} (or no filter) still allows every row. Each refusal is logged as a warning (Row filter ...; write refused, with the policy id when a part adds no condition), so an admin can find and fix the filter.

The validation filter is checked on the payload of create and update (validatePayload): all matching records' rules must pass (AND), and a key absent from the payload is not checked.

Query filters through a relation (validateFilterAccess): a filter that reads a related row (filter[author][email][_eq]=…) needs read on the related collection, from the same grant a fields=author.email read uses (explicit records, or the app-access synthetic grant with its row scope); that collection's rows (the OR of its records) and masks apply inside the filter. A bare foreign key (filter[author][_eq]=<id>, filter[author][_null]=true) compares the row's own column and needs only read on that column.

Dynamic variables:

  • $CURRENT_USER — Current user's UUID
  • $CURRENT_ROLE — Current user's primary role UUID
  • $CURRENT_ROLES — Array of current user's role UUIDs
  • $CURRENT_POLICIES — Array of the current user's policy UUIDs (not available on accountability — resolves to [])
  • $NOW — Current timestamp

Permission Endpoints ​

Table prefix: /permissions

POST /permissions ​

json
{
  "policy": "policy-uuid",
  "collection": "articles",
  "action": "read",
  "fields": ["*"],
  "permissions": {
    "status": { "_eq": "published" }
  }
}

GET /permissions ​

List all permissions. Admin access.

GET /permissions/me ​

Get all permissions applicable to the current user (resolves from roles and policies). Any authenticated user.

GET /permissions/:id ​

Read a single permission. Admin access.

PATCH /permissions/:id ​

Update a permission. Admin access.

DELETE /permissions/:id ​

Delete a permission. Admin access.


App-Level Permissions ​

Beyond collection-level RBAC, certain modules (Workflow, etc.) use app-level permissions stored in odp_app_permissions. These control access to specific module actions:

ModuleActions
workflowview, start, participate, manage

App permissions are checked via validateAppAccess(accountability, module, action, collection, knex) in src/permissions/index.ts.


How Permissions Are Evaluated ​

  1. Admin users (admin_access: true) bypass all RBAC.
  2. Tech users (tech_access: true) imply admin_access.
  3. App-access synthetic grant — an app_access user passes validateAccess for the collections in appAccessMinimalPermissions even with no explicit permission record, and returns before the policy system runs (src/permissions/validate-access.ts:53). That check is the action only. When the user has no explicit record, the grant's own row, field and payload scope applies downstream (getAppAccessFallbackPermission): the bullets below list the scoped collections; the others (schema metadata, translations, settings) are read-all.
    • #34 fail-closed own-row scoping (READ): on the read path, when an app-access user hits a user-scoped collection (activity, notifications, presets, shares, user-providers) with no explicit record, processAst injects the collection's own-rows filter instead of returning the whole table (src/permissions/process-ast.ts:78-87, appAccessRowScopes in src/permissions/app-access-permissions.ts). Global/shared collections keep read-all.
    • Own-row scoping (presets, WRITE): with no explicit record on odp_presets, an app-access user reads their own rows plus shared rows (user IS NULL), but writes their own rows only. Update and delete are bound to user = $CURRENT_USER (appAccessActionRowScopes), and create and update refuse a payload whose user is not the caller (appAccessActionValidations), so a preset cannot be made shared or moved to another user. Sharing a preset needs an admin or an explicit policy on odp_presets.
    • OpenUI templates (odp_ui_templates): with no explicit record, an app-access user reads their own rows, rows shared to their primary role ($CURRENT_ROLE, exact match: no parent or child roles), and global rows. They write their own personal rows only: update and delete are bound to user_created = $CURRENT_USER and scope = 'personal', so an author cannot change a row once an admin shares it. Create and update refuse scope other than personal, and create refuses a user_created that is not the caller. share_roles is never writable and is not returned (no grant on odp_ui_templates_roles or odp_roles); user_created, date_created and id cannot change on update. Sharing and shared defaults are admin-only in UiTemplatesService, whatever the policies.
    • Owner-only collections (agentic chat history, src/permissions/owner-only.ts): odp_ai_agentic_conversations and odp_ai_agentic_messages hold one user's rows, owner column user_id. Every generic read path (ItemsService, nested relations, relational filters, counts) returns the caller's own rows only, admin and explicit policies included. Every stored record on these tables is ANDed with user_id = $CURRENT_USER. No caller may create or update them through ItemsService; only the history service writes. An impersonation token reaches none of their rows. Without an explicit record, an app user may read both tables and delete its own conversations. This holds for every API path. In-process code (extensions, hooks) that builds services with an admin accountability is trusted and is not bound by it.
  4. For non-admins without a synthetic grant, the service loads all policies attached to the user's roles.
  5. Policies are merged — if any policy grants access, the action is allowed.
  6. Row-level filters of several matching records are OR-combined, on read and on update/delete (see "Several records on one collection and action" above).
  7. A field shows, or may be updated, on a row only where a record granting it matches that row. On create, the field lists are united.

Role-Policy Assignment ​

Roles are linked to policies via the odp_access junction table.

Assign a policy to a role:

bash
PATCH /roles/:roleId
{
  "policies": ["policy-uuid-1", "policy-uuid-2"]
}

Example: Setting Up an Editor Role ​

bash
# 1. Create a policy
POST /policies
{
  "name": "Article Editor",
  "app_access": true
}
# Returns: { "data": "policy-abc" }

# 2. Add permissions to the policy
POST /permissions
{
  "policy": "policy-abc",
  "collection": "articles",
  "action": "read",
  "fields": ["*"]
}

# Update on the allowed fields, own rows only: verifyRowAccess enforces the
# filter before the write (see "Update and delete filters fail closed").
POST /permissions
{
  "policy": "policy-abc",
  "collection": "articles",
  "action": "update",
  "fields": ["title", "content", "status"],
  "permissions": { "author_id": { "_eq": "$CURRENT_USER" } }
}

# 3. Create the role and assign the policy
POST /roles
{
  "name": "Editor",
  "app_access": true,
  "policies": ["policy-abc"]
}

# 4. Assign role to user
PATCH /users/:userId
{
  "role": "role-uuid"
}

ODP Internal API Documentation