Roles & Permissions

Ironflow ships with built-in roles for both tenant and platform operations. All roles are stored in a unified roles table and enforced via RBAC on every authenticated request.

Built-in Tenant Roles

Role	Description
admin	Full access — all read, write, and delete operations
developer	Read and write access — can create and modify resources
viewer	Read-only access — can list and read resources

Built-in Platform Roles

Role	Description
platform_admin	Full access to all platform operations (wildcard permission)
platform_operator	Tenant management, impersonation, read access to users/keys/roles/policies, audit read
platform_viewer	Read-only access to all platform resources

See Platform Roles & Actions for the complete platform permissions matrix.

Permissions Matrix

The table below lists the core permission actions and which roles can perform them. Three admin-only actions are matched solely by the admin wildcard and are omitted here: org:export (GET /api/v1/export), cluster:rotate-token (POST /api/v1/cluster/rotate-token), and platform:tenants:manage — which is what POST /api/v1/orgs costs, because orgs are provisioned by platform callers rather than self-provisioned by a tenant (#660).

Action	Admin	Developer	Viewer
functions:register	✓	✓
functions:invoke	✓	✓
functions:list	✓	✓	✓
functions:read	✓	✓	✓
runs:read	✓	✓	✓
runs:cancel	✓	✓
events:emit	✓	✓
events:subscribe	✓	✓	✓
outbox:manage	✓	✓
streams:read	✓	✓	✓
entities:read	✓	✓	✓
entities:append	✓	✓
projections:read	✓	✓	✓
projections:manage	✓	✓
secrets:read	✓	✓
secrets:manage	✓
users:read	✓	✓	✓
users:manage	✓
apikeys:read	✓	✓	✓
apikeys:manage	✓	✓
orgs:read	✓	✓	✓
orgs:manage	✓
agent:tools:register	✓	✓
agent:tools:invoke	✓	✓
agent:tools:unregister	✓	✓
agent:tools:read	✓	✓	✓

Admin wildcard

The admin role uses a single wildcard (*) that matches every action, including any new actions added in future versions.

How Actions Are Resolved

Each incoming request is mapped to a permission action based on the HTTP method and path:

• ConnectRPC — the RPC method name determines the action. Mutating RPCs cost more than reads: function registration/status/deletion requires functions:register; Trigger* and Emit require events:emit; run cancellation and step patching require runs:cancel; entity appends and snapshot creation require entities:append; projection registry/state/cursor/rebuild mutations require projections:manage. Read and subscribe methods retain their resource’s read action. The route inventory is derived from protobuf descriptors, so a new RPC cannot be omitted from the RBAC coverage gate by forgetting a parallel route list.
• REST API — the HTTP method, first path segment, and any verb sub-path determine the action. Most routes follow method + resource (e.g. GET /api/v1/users → users:read, POST /api/v1/users → users:manage), but the mapping is a hand-written switch, not a formula: GET /api/v1/events costs events:subscribe (there is no events:read), the KV and config segments resolve to the secrets:* pair, and GET /api/v1/environments costs functions:list while its writes cost secrets:manage. Verb sub-paths override (e.g. POST /api/v1/circuit-breakers/{key}/reset → functions:invoke).
• WebSocket — the /ws upgrade requires events:subscribe

If a request maps to an action that the caller’s roles don’t include, the server returns 403 Forbidden. If no valid credentials are provided at all, the server returns 401 Unauthorized.

IRN (Ironflow Resource Naming)

Every resource in Ironflow has a unique identifier following the IRN format:

irn:ironflow:{org_id}:{project_id}:{type}:{environment}:{resource}

On REST requests the type comes from the first path segment, singularized. Eleven segments have a singular form: function, run, event, stream, projection, secret, org, role, policy, user, project. Every other segment is used verbatim, so /api/v1/apikeys/{id} names ...:apikeys:... — plural. Write the pattern to match the segment you see, not a singular you expect.

IRN patterns support wildcards (*) for any segment, enabling flexible permission matching. A pattern only matches an IRN with the same number of segments, so a bare * is the only pattern that matches everything.

Custom Roles

Beyond the built-in roles, you can create custom roles scoped to an organization. Custom roles have no built-in permissions — they derive all access from attached policies.

Managing Custom Roles

# Create a custom role
ironflow role create billing-team --org org_default

# List all roles (built-in + custom)
ironflow role list --org org_default

# Get a single role
ironflow role get <role_id>

# Assign a policy to a role
ironflow role assign-policy <role_id> <policy_id>

# Remove a policy from a role
ironflow role remove-policy <role_id> <policy_id>

# Delete a custom role (built-in roles cannot be deleted)
ironflow role delete <role_id>

Policy-Based Authorization

Policies define fine-grained access rules using actions, resource patterns, and optional CEL conditions.

Field	Description	Example
name	Human-readable policy name (unique per org)	deny-weekend-deploys
effect	deny only (#943, ADR 0016 T2 — see Evaluation Rules)	deny
actions	Comma-separated action patterns (wildcards supported)	functions:list,runs:read
resources	Comma-separated IRN patterns (wildcards supported)	irn:ironflow:*:*:function:env_prod:*
condition	Optional CEL expression (must return boolean)	request.environment == "env_prod"

Evaluation Rules

Authorization is two-layered:

1. System RBAC (Layer 1) is the authoritative ALLOW gate. If the caller’s roles do not grant the action, access is denied immediately — CEL policies are not consulted.
2. CEL policies (Layer 2) are subtractive only. Only deny-effect policies are evaluated. As of #943 (ADR 0016 T2), effect=allow is rejected at write with HTTP 400 (policy_effect_allow_deprecated) across every input surface (server API, platform API, template install, CLI, dashboard, SDK). Legacy allow rows in the database are inert at evaluation and are removed by migration 030.
3. Matching deny policies have their CEL conditions evaluated. Deny always wins — if any matching deny policy’s condition passes, access is denied.
4. If RBAC allowed and no deny policy matches (or no policies exist), access is allowed.

To grant a capability that RBAC does not currently provide, edit the role assignment (Layer 1). Do not attempt to express grants as Layer 2 policies — that path is by design closed.

Managing Policies

# Create a deny policy with CEL condition
ironflow policy create \
  --name deny-weekend-deploys \
  --effect deny \
  --actions "functions:register" \
  --resources "irn:ironflow:*:*:function:env_prod:*" \
  --condition 'request.timestamp.getDayOfWeek() == 0 || request.timestamp.getDayOfWeek() == 6'

# List policies
ironflow policy list --org org_default

# Get a single policy
ironflow policy get <policy_id>

# Update a policy (creates a new version)
ironflow policy update <policy_id> --actions "..." --resources "..."

# Test a policy against a sample request
ironflow policy test --policy-id <policy_id> --request-file request.json

# List a policy's version history
ironflow policy versions list <policy_id>

# Roll back to a previous version
ironflow policy rollback <policy_id> <version>

# Install a policy template bundle
ironflow policy template install <template_id>

# Delete a policy
ironflow policy delete <policy_id>

For full details on CEL expressions and the REST API, see Custom Roles & CEL Policies.

outbox:manage

Requeueing or discarding a transactional-outbox dead-letter entry requires outbox:manage. Listing them requires only events:subscribe, because the row carries the same payload a subscriber would have received.

These writes previously cost events:emit. That undercharged them: events:emit is the ordinary application permission every SDK key holds, while ironflow outbox dlq discard destroys every dead-letter row sharing an event_id and cannot be undone. Operating the outbox is an operator act, not an application one.

Built-in roles are unaffected — Admin is *, Developer holds both permissions, and Viewer held neither. If you have defined a custom role that granted events:emit in order to reach the dead-letter endpoints, add outbox:manage to it.