Account lifecycle status¶

When you onboard an organization at scale, most of its accounts are created as cheap placeholders and only become fully set up when someone actually uses them. Every account therefore carries a lifecycle status, and that status is the same value on the API, in the CLI, and in anything you build on top.

All paths are under the public gateway at https://api.flexgalaxy.ai. The wire is snake_case. See Provisioning at scale for the bulk-create call itself.

Two independent axes¶

An account has two things that can be set up, and they are set up separately, each on first use.

Field	Values	What it tracks
`status`	`PLACEHOLDER` · `MATERIALIZING` · `ACTIVE` · `CLOSED`	whether the account is a real, assignable, operable authorization target
`realm_status`	`NONE` · `MATERIALIZING` · `ACTIVE`	whether the account has its own identity realm, which hosts that account’s service users

`status`	Meaning
`PLACEHOLDER`	The account exists as a row in the organization tree. Nothing has been provisioned for it. It cannot yet be operated.
`MATERIALIZING`	Transient — a first-use trigger is in flight. Treat it as “not ready yet” and re-read.
`ACTIVE`	The account is a real authorization target: permission sets can be assigned to it and workforce users can operate it.
`CLOSED`	Terminal. Closing is a pure state transition — backing resources are retained and the account stays auditable.

realm_status is NONE for the large majority of accounts and stays that way. Workforce operators are Identity Center users, so granting people access never needs the account’s own realm; only a service user (a machine / access-key principal) does. realm_status can only leave NONE once status is ACTIVE.

What moves an account forward¶

Call	Effect
`POST /organizations/v1/{org}/onboarding/accounts`	bulk-create placeholders — `202`, each `PLACEHOLDER` / `NONE`
`POST /organizations/v1/{org}/onboarding/accounts/{account}:grant-operator`	first operator grant → `status` `PLACEHOLDER` → `ACTIVE`
`POST /organizations/v1/{org}/onboarding/accounts/{account}:provision-service-user`	first service user → `realm_status` → `ACTIVE` (materializing `status` first if needed)
`POST /organizations/v1/{org}/onboarding/accounts/{account}:close`	→ terminal `CLOSED`, idempotent
`POST /organizations/v1/{org}/onboarding/accounts/{account}:purge`	`204` hard-delete of a never-materialized placeholder

Every one of these is idempotent and safe to retry: re-granting the first operator, re-provisioning the first service user, and re-closing an already-closed account all converge on the same result.

:purge only accepts an account that is still PLACEHOLDER and NONE. Once either axis has materialized, purge returns 409 not_a_placeholder — close it instead.

Read the status¶

GET /organizations/v1/{org}/account-lifecycle

Add ?status=PLACEHOLDER|MATERIALIZING|ACTIVE|CLOSED to filter. An unrecognized value returns 400 bad_request listing the accepted values, so a typo never comes back as a silently empty result.

[
  {
    "account_id": "6f1c…",
    "org_id": "7b39…",
    "ou_node_id": "a2d0…",
    "name": "warehouse-01",
    "status": "ACTIVE",
    "realm_status": "NONE",
    "version": 3,
    "created_at": "2026-07-24T02:11:07Z",
    "updated_at": "2026-07-24T09:40:55Z",
    "activated_at": "2026-07-24T09:40:55Z"
  }
]

activated_at / realm_activated_at are present only once the corresponding axis has reached ACTIVE; null fields are omitted.

Note

This endpoint is not paginated and returns the whole result set, ordered oldest-first. For an organization with thousands of accounts, always pass ?status=, or walk the tree with the paginated organization reads described in Provisioning at scale.

Authorization matches the rest of the organization surface: a signed-in workforce caller is scoped to its active organization; an AK/SK service principal is authorized by management-account ownership.

The same thing on the CLI¶

fgai org account-lifecycle --org <org>
fgai org account-lifecycle --org <org> --status PLACEHOLDER

fgai org onboard-grant-operator          --org <org> --account <account>
fgai org onboard-provision-service-user  --org <org> --account <account>
fgai org onboard-close                   --org <org> --account <account>
fgai org onboard-purge                   --org <org> --account <account>

Status decides where an app opens¶

PassPort routes a user to an onboarding entry instead of the app homepage when the account they are entering is still PLACEHOLDER or MATERIALIZING, and a CLOSED account has no entry at all. See PassPort app launch & app-entry.