Ironflow is pre-1.0: APIs can change between releases. Pin a version. What is ready →

Platform Roles & Actions

Built-in Roles

Role	Description
`platform_admin`	Full access to all platform operations. Wildcard (`*`) permission.
`platform_operator`	Tenant management, full impersonation (read + write), read access to users, keys, roles, the policy set, and the audit log, plus instance read and freeze.
`platform_viewer`	Read-only access to all platform resources.

The three built-in platform roles are seeded by migration into org_platform. Custom platform roles can be created — see Platform RBAC.

Built-in platform roles cannot be deleted or renamed via the API. Attempts to do so return 400 cannot delete built-in role / 400 cannot update built-in role and emit a delete_blocked / update_blocked audit event.

Actions

Action	Description
`platform:users:read`	List and view platform users
`platform:users:manage`	Create, update, and delete platform users
`platform:keys:read`	List and view platform API keys
`platform:keys:manage`	Create, rotate, and delete platform API keys
`platform:roles:read`	List and view platform roles
`platform:roles:manage`	Create, update, and delete custom roles
`platform:tenants:read`	List and view tenant organizations
`platform:tenants:manage`	Provision and delete tenant organizations
`platform:impersonate:read`	Read-only impersonation of tenant orgs (endpoints whose RBAC action is a read)
`platform:impersonate`	Write access to tenant orgs (every other endpoint)
`platform:audit:read`	Query the platform audit log
`platform:policies:read`	View the platform policy set and its versions
`platform:policies:manage`	Write, validate, dry-run and roll back the platform policy set, and force a tenant set to monitor mode
`platform:instance:read`	Read the instance barrier and drain state
`platform:instance:freeze`	Freeze and thaw the instance
`platform:instance:reconcile`	Reconcile one drain obligation
`platform:instance:attest`	Attest instance coverage for a boundary
`platform:bootstrap`	Run the one-time platform bootstrap. Only an admin of the default organization holds it; no built-in platform role is needed.

Actions by Role

Action	Admin	Operator	Viewer
`platform:users:read`	Yes	Yes	Yes
`platform:users:manage`	Yes	—	—
`platform:keys:read`	Yes	Yes	Yes
`platform:keys:manage`	Yes	—	—
`platform:roles:read`	Yes	Yes	Yes
`platform:roles:manage`	Yes	—	—
`platform:tenants:read`	Yes	Yes	Yes
`platform:tenants:manage`	Yes	Yes	—
`platform:impersonate:read`	Yes	Yes	Yes
`platform:impersonate`	Yes	Yes	—
`platform:policies:read`	Yes	Yes	Yes
`platform:policies:manage`	Yes	—	—
`platform:audit:read`	Yes	Yes	Yes
`platform:instance:read`	Yes	Yes	Yes
`platform:instance:freeze`	Yes	Yes	—
`platform:instance:reconcile`	Yes	—	—
`platform:instance:attest`	Yes	—	—

HTTP Method Mapping

The platform middleware maps HTTP methods and paths to actions:

Path Pattern	GET	POST/PUT/DELETE
`/api/v1/platform/users*`	`platform:users:read`	`platform:users:manage`
`/api/v1/apikeys?platform=true`	`platform:keys:read`	`platform:keys:manage`
`/api/v1/platform/roles*`	`platform:roles:read`	`platform:roles:manage`
`/api/v1/platform/policy-set*`	`platform:policies:read`	`platform:policies:manage`
`/api/v1/platform/tenants` (or `/api/v1/platform/orgs`)	`platform:tenants:read`	`platform:tenants:manage`
`/api/v1/platform/audit*`	`platform:audit:read`	`platform:audit:read`
`/api/v1/platform/instance*`	`platform:instance:read`	`platform:instance:freeze` for `freeze` and `thaw`, `platform:instance:attest` for `coverage/attest`, `platform:instance:reconcile` for `obligations/{id}/reconcile`
`/api/v1/platform/auth*`	(public)	(public)
`/api/v1/platform/bootstrap`	n/a	`platform:bootstrap` (held only by an admin of the default organization; refuses once any platform user exists)

Notes:

Platform API keys are listed/managed through the tenant /api/v1/apikeys route with ?platform=true; the action is selected inline by the apikey handler (platform:keys:read for GET, platform:keys:manage otherwise).
The audit path maps to platform:audit:read for any HTTP method. Only GET routes are registered today, so non-GET requests 404 before authz runs.

For impersonation (non-platform endpoints with X-Ironflow-Org header):

Endpoint	Required Action
RBAC action is a read (`:read`, `:list`, `:subscribe`)	`platform:impersonate:read`
Any other RBAC action	`platform:impersonate`
No RBAC action, and the method is GET, HEAD or OPTIONS	`platform:impersonate:read`
No RBAC action, any other method	`platform:impersonate`

The endpoint’s action decides, not the HTTP method. A ConnectRPC read is a POST and needs only read impersonation; GET /api/v1/export (org:export), GET /api/v1/workers and GET /api/v1/workers/{workerId}/jobs (functions:invoke), and GET /api/v1/debug/requests (orgs:manage) are writes and need the full action.

HEAD is a rough edge: the action map has no HEAD arm, so HEAD on most mapped read routes resolves to that resource’s write action and needs full impersonation. It fails closed, and it affects tenant roles through the same map.

ID Formats

Resource	Prefix	Example
Platform user	`puser_`	`puser_a1b2c3d4`
API key (all types)	`ak_`	`ak_e5f6g7h8`
Role (built-in)	`role_`	`role_platform_admin`
Role (custom platform)	`prole_`	`prole_a1b2c3d4`
Tenant (organization)	`org_`	`org_x1y2z3w4`
Platform key value	`ifplatform_`	`ifplatform_a1b2...` (43 chars)
Tenant key value	`ifkey_`	`ifkey_a1b2...` (38 chars)