#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.

These four names are the project_role enum, and they scope project membership and project API tokens. Organization membership uses a separate vocabulary — owner, admin, member — owned by the auth layer, not by this matrix. The two namespaces are deliberately distinct: an org admin is not a project admin, and an org role grants no project-scoped access at all (projectAuthMiddleware resolves the role from the caller's project membership or token, never from their org role). Org role is consulted only on the org-scoped project-administration routes — deleting a project and managing its member roster — where an org owner acts with project owner capability and an org admin with project admin capability.

#Permission strings

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

#The role-to-permission matrix

Each ✓ is a permission the role holds. The roles are declared as composed sets in PROJECT_ROLE (@terrantula/types) — read ⊂ write ⊂ admin ⊂ owner — and the permission guard every route's contract() declaration derives imports that declaration rather than keeping its own copy.

So in plain terms:

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

#How routes are gated

Every project-scoped route is built with contract() (packages/api/src/lib/contract.ts) — a single declaration per route that is simultaneously its OpenAPI documentation and its enforcement. There is no middleware to mount by hand: a route declares its permission, and contract() derives the guard from that declaration and runs it after projectAuthMiddleware has set the caller's project role on the request context.

// Apply is write-only and admin+.
const applyContract = {
  operationId: 'applyChanges',
  auth: 'project',
  permission: 'apply:write',
  // ...
} satisfies ProjectContract
app.post('/:o/:p/apply', ...contract(applyContract), handler)

A route whose read/write split falls cleanly along the HTTP method declares the permission per method — one contract() call per operation, each with its own permission:

// GET needs secrets:read (admin and above); PUT needs secrets:set-value.
const getStatusContract = { operationId: 'getSecretValueStatus', auth: 'project', permission: 'secrets:read', /* ... */ } satisfies ProjectContract
const setValueContract = { operationId: 'setSecretValue', auth: 'project', permission: 'secrets:set-value', /* ... */ } satisfies ProjectContract
app.get('/:o/:p/secrets/:name/value', ...contract(getStatusContract), handler)
app.put('/:o/:p/secrets/:name/value', ...contract(setValueContract), handler)

The permission guard itself (requirePermission) is not a public export of any package — it lives inside packages/api/src/lib/require-permission.ts, package-private to packages/api, and contract() is its only caller. A route file can declare a permission; it cannot mount the guard by hand.

#Permission-to-route map

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

Two more permissions are enforced off this surface, on the org-scoped project routes (/orgs/:orgId/projects/:projectId…), because they act on the project itself rather than on anything inside it. They are checked inside the handler rather than by requirePermission middleware, but the answer comes from the same PROJECT_ROLE declaration:

#Caveats

#Related

• API Reference — every route annotated with its required permission.
• Drift events — what data:read / drift:resolve 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.