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, policies, and the audit log.
`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`	List and view platform policies
`platform:policies:manage`	Create, update, and delete platform policies

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

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/policies*`	`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/auth*`	(public)	(public)
`/api/v1/platform/bootstrap`	n/a	(no platform action; requires a tenant admin API key and 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`
Policy (unified)	`pol_`	`pol_def456`
Tenant (organization)	`org_`	`org_x1y2z3w4`
Platform key value	`ifplatform_`	`ifplatform_a1b2...` (43 chars)
Tenant key value	`ifkey_`	`ifkey_a1b2...` (38 chars)