Platform Management

This tutorial walks you through the full platform lifecycle: bootstrapping an admin, creating API keys, provisioning tenants, impersonating them, and inspecting the system’s recorded history.

Prerequisites: A running Ironflow server started without --dev. Every server carries the platform routes; there is no separate platform mode. With --dev, each request is treated as a default-organization admin and never as a platform principal, so the platform routes answer 403.

---

1. Bootstrap the Platform Admin

Create the initial platform administrator. This command only works when no platform users exist yet. It requires an admin API key of the default organization (ifkey_... in IRONFLOW_API_KEY), the key the first server start writes to the bootstrap key file. Platform login isn’t available until the first user exists. A key with a lower role, or an admin key of another organization, gets 403.

IRONFLOW_API_KEY="ifkey_..." ironflow platform create-admin --email admin@example.com --name "Platform Admin"

You’ll be prompted for a password:

Password: ********
Created platform admin: admin@example.com (id: puser_a1b2c3d4)

Tip

The create-admin command is a one-time bootstrap. After the first admin exists, create additional users with ironflow platform users create --email <email> --name "<name>" (both flags required).

---

2. Log In

Authenticate with the platform to get a JWT token stored at ~/.config/ironflow/credentials.json:

ironflow platform login --email admin@example.com

Password: ********
Logged in as admin@example.com (expires: 2026-03-13T10:00:00Z)

The token is valid for 24 hours. All subsequent ironflow platform commands use this token automatically.

You can also log in via the dashboard at http://localhost:9123/platform/login using the same credentials.

---

3. Create a Platform API Key

Platform API keys authenticate automated systems (CI/CD, scripts) without user credentials. ironflow apikey create authenticates with IRONFLOW_API_KEY, not with the login from step 2, so pass the default organization’s admin key again. A platform key holds only the roles you give it and can do nothing without one. Pass --role with a platform role ID; ironflow platform roles list shows them.

IRONFLOW_API_KEY="ifkey_..." ironflow apikey create my-automation-key --platform --role role_platform_admin

Created Platform Key: my-automation-key (id: ak_e5f6g7h8)
Key: ifplatform_a1b2c3d4e5f60123456789abcdef0123

Save this key — it will not be shown again.

Caution

The full key value is only displayed once at creation time. Store it securely.

---

4. Provision a Tenant

Create a tenant organization with its built-in roles, a project, an environment, and an admin API key. Like step 3, this command authenticates with the default organization’s admin key:

IRONFLOW_API_KEY="ifkey_..." ironflow tenant provision --name "Acme Corp"

Created org: Acme Corp (org_acme-corp)
Created env: production (env_acme-corp_production)
Admin API Key: ifkey_a1b2c3d4e5f60123456789abcdef0123

Note

ironflow platform tenants provision --name "Acme Corp" creates the organization only. That tenant has no project, environment, or admin API key, and step 5 cannot impersonate it.

List all tenants to verify. The default organization is in the list too:

ironflow platform tenants list

ID             NAME       CREATED
org_default    default    2026-03-12T08:00:00Z
org_acme-corp  Acme Corp  2026-03-12T10:00:00Z

---

5. Impersonate a Tenant

Use the --as-org persistent root flag to run a command as if you were inside a tenant’s organization. Impersonation always targets one environment of the tenant, so name it by ID with the command’s --env flag. Without --env the server falls back to env_default, which belongs to the default organization, and every other tenant answers 403.

ironflow --as-org org_acme-corp circuit-breaker list --env env_acme-corp_production

No circuit breakers found

The list is empty because the new tenant has no functions yet.

--as-org acts on the commands that call the server over REST: apikey, circuit-breaker, debounce, env, org, outbox, policy, project, role, secret, tenant and webhook. It also acts on inspect and the WebSocket commands, which read IRONFLOW_ENV as the environment selector. Other ConnectRPC commands such as function list, run list and emit accept the flag and ignore it. Of the REST commands, only circuit-breaker, outbox and secret send --env as the environment selector. To reach anything else in a tenant, use the HTTP form in Impersonating Tenants.

Tip

Read-only operations (like list) require the platform:impersonate:read permission. Write operations require platform:impersonate. The built-in platform_admin role has both.

---

6. Inspect History

The platform audit log records platform user changes, blocked changes to built-in platform roles, and every impersonated request. Logging in, bootstrapping the first admin with create-admin, provisioning tenants, and creating API keys write no platform audit row. Query the log:

ironflow platform audit

ID                           EVENT_TYPE             SCOPE     CREATED_AT
01HXYZ...                    platform.impersonated  platform  2026-03-12T09:10:00Z

Total: 1

Filter and paginate with --event-type, --from, --to, --limit, --cursor. Use --json for machine-readable output:

ironflow platform audit --event-type platform.impersonated --from 2026-03-12 --limit 50 --json

For the full list of event types, see Audit Logging.

---

Next Steps

• Managing Platform Users & Keys — full CRUD operations
• Impersonating Tenants — read vs write access, HTTP headers, audit implications
• Platform RBAC — built-in roles, custom roles, action reference
• Platform Architecture — how the dual auth model works under the hood