#RBAC roles & permissions

Every project-scoped route is gated by a permission string. A caller's project role maps to a fixed set of permissions; a route demands one permission and rejects any caller whose role does not hold it. The matrix is hardcoded — changing it requires a deploy, which keeps it auditable.

There are four roles and a flat vocabulary of permission strings. This page is the lookup reference for both.

#Roles

A caller acts on a project with exactly one role, set on their project membership (or carried by a project API token). The role is resolved by projectAuthMiddleware before any permission check runs.

The same four roles also scope organization membership and project API tokens (the member_role enum: owner, admin, member, viewer).

#Permission strings

Permissions are flat resource:action strings. The full vocabulary:

#The role-to-permission matrix

Each ✓ is a permission the role holds. Grounded in the hardcoded map in @terrantula/rbac.

So in plain terms:

• viewer can read everything in the catalog and data plane and view saved graph views — nothing more.
• member adds data writes (entities, relationships, running actions, resolving drift events) and personal saved-view CRUD, but still cannot touch the catalog schema, secrets, tokens, or apply.
• admin and owner hold every permission.

#How routes are gated

Two middleware factories from @terrantula/rbac enforce the matrix. Both run after projectAuthMiddleware has set the caller's project role on the request context.

#requirePermission

Demands one explicit permission. The caller's role must include it, or the request gets 403 Forbidden.

// Apply is write-only and admin+.
app.use('/:o/:p/envs/:envName/apply/*', requirePermission('apply:write'))

#requireMethodPermission

A convenience for routes whose read/write split falls cleanly along the HTTP method: GET requires the read permission, everything else requires the write permission.

// Reads need data:read (all roles); writes need data:write (member+).
app.use(
  '/:o/:p/envs/:envName/entities/*',
  requireMethodPermission('data:read', 'data:write'),
)

#Permission-to-route map

The permission each project-scoped route family demands. (The API Reference lists the exact permission on every endpoint.)

#Caveats

#Related

• API Reference — every route annotated with its required permission.
• Drift events — what data:read / data:write gate on the drift surface.
• Configuration Reference — project API tokens and the role they carry.
• Triggers, GitHub App, Actions & Webhooks — the HMAC-authenticated webhook surface that bypasses RBAC.