Impersonating Tenants

Impersonation lets platform administrators perform operations within a tenant’s organization without needing that tenant’s credentials. Every impersonated request is recorded in the audit trail.

---

When to Use Impersonation

• Debugging — inspect a tenant’s functions, runs, or events
• Support — fix configuration issues on behalf of a tenant
• Provisioning — set up initial resources in a newly created tenant

---

CLI: The --as-org Flag

Add --as-org <org_id> to any Ironflow command to run it as the specified tenant:

# List a tenant's environments
ironflow --as-org org_x1y2z3w4 env list

# List a tenant's projects
ironflow --as-org org_x1y2z3w4 project list

The --as-org flag requires platform credentials (from ironflow platform login).

---

HTTP: The X-Ironflow-Org Header

For direct API calls, set the X-Ironflow-Org header to the target organization ID:

# List a tenant's functions
curl http://localhost:9123/api/v1/functions \
  -H "Authorization: Bearer $PLATFORM_TOKEN" \
  -H "X-Ironflow-Org: org_x1y2z3w4"

Specifying an Environment

By default, impersonated requests target the tenant’s env_default environment. To target a different environment, add the X-Ironflow-Environment header or ?env query parameter:

curl http://localhost:9123/api/v1/functions \
  -H "Authorization: Bearer $PLATFORM_TOKEN" \
  -H "X-Ironflow-Org: org_x1y2z3w4" \
  -H "X-Ironflow-Environment: env_staging"

The environment must belong to the impersonated organization.

---

Read vs Write Access

Impersonation has two permission levels:

Permission	HTTP Methods	Description
platform:impersonate:read	GET, HEAD, OPTIONS	Read-only access to tenant data
platform:impersonate	POST, PUT, PATCH, DELETE	Write access (create, update, delete) to tenant data

Built-in role assignments:

Role	Read	Write
platform_admin	Yes	Yes
platform_operator	Yes	Yes
platform_viewer	Yes	No

Caution

Write impersonation is a powerful operation. It allows creating, modifying, and deleting resources within a tenant’s organization. Both platform_admin and platform_operator have write impersonation by default.

---

Audit Trail

Every impersonated request generates a platform.impersonated audit event containing:

• The platform user or key that initiated the request
• The target organization ID
• The HTTP method and path

Query impersonation events:

ironflow platform audit --event-type platform.impersonated

Filter by target tenant (via HTTP API — this filter is not available in the CLI):

curl "http://localhost:9123/api/v1/platform/audit?impersonated_org_id=org_x1y2z3w4" \
  -H "Authorization: Bearer $PLATFORM_TOKEN"

See Platform Architecture for details on how the dual audit model works.

---

Next Steps

• Managing Platform Users & Keys — create users and keys with impersonation roles
• Platform RBAC — configure which roles have impersonation access
• Platform API Reference — full endpoint documentation