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: An Ironflow server running in Platform mode.

---

1. Bootstrap the Platform Admin

Create the initial platform administrator. This command only works when no platform users exist yet. It requires a tenant API key (ifkey_... in IRONFLOW_API_KEY) — platform login isn’t available until the first user exists, and platform keys (ifplatform_) do not bypass this rule.

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 my-automation-key --platform

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

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 new tenant organization:

ironflow platform tenants provision --name "Acme Corp"

Provisioned tenant: Acme Corp (id: org_x1y2z3w4)

List all tenants to verify:

ironflow platform tenants list

ID              NAME        CREATED
org_x1y2z3w4    Acme Corp   2026-03-12T10:00:00Z

---

5. Impersonate a Tenant

Use the --as-org persistent root flag (works with any Ironflow command) to run as if you were inside a tenant’s organization:

ironflow --as-org org_x1y2z3w4 env list

ID              NAME      CREATED
env_default     default   2026-03-12T10:00:00Z

This works with any Ironflow command. For example, listing the tenant’s functions:

ironflow --as-org org_x1y2z3w4 function list

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

Every platform operation is recorded in the platform audit log. Query it:

ironflow platform audit

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

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

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

---

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