External application with its own hierarchy — runnable example

Runnable code: examples/external-app-own-hierarchy/ (in the DotID repository).

This example is the companion to external-app-own-hierarchy. It drives the full “the application brings its own hierarchy” pattern against the live platform through the published API and the shipped fgai CLI only — no internal endpoints, no privileged shortcuts. Everything a platform developer does in this example, an external application can do with the same public surface.

What it does

  1. Creates an organization with a root OU, an area OU, a city OU, store OUs, and a placeholder account per store.

  2. Sets up four roles with distinct reach:

    • BROIT robot (service user) — runs the nightly clearjanitor task;

    • store staff — operates in a single store account;

    • area-company workforce — manages every store under the area OU through one OU-scoped assignment;

    • delegated administrator — an area-company account delegated a slice of admin over the area, capped by a permission boundary.

  3. Verifies every grant end-to-end (fgai authorize check) against the live policy decision service, including an Identity Center session minted for an OU-assigned permission set.

  4. Tears everything down again, leaving the pre-existing application hierarchy untouched.

Prerequisites

  • fgai CLI (dl.flexgalaxy.ai), configured against prod with an authentication profile that may create organizations.

  • FGAI_CLI_HOME set (the CLI’s configuration home).

Status: the delegated-administrator leg requires the platform to provision an account-scoped authoring role inside org member accounts. That provisioning has landed in code (DotID#291) but is not deployed to the live platform yet; until it is, the driver exercises the leg adaptively and reports its checks as skipped when the role is absent.

Run

npm run setup     # create org + hierarchy + principals + grants
npm run verify    # prove every grant with authorize check
npm run summary   # print the scenario state
npm run teardown  # close accounts, delete OUs, remove delegations

The driver is src/broit-area-robot-management.mjs. It is re-runnable: state is tracked in .ph103-state.json at the example root, and a transient network retry is built in.

What the verification proves

  • Placeholder accounts are granted operators and materialize; the same grants resolve through the public policy simulator.

  • One OU-scoped assignment on the area OU authorizes a workforce principal for every store account under it — reach comes from the OU ancestry lookup at assignment time.

  • The permission boundary on the delegated administrator refuses the grant the assignment would otherwise allow.

  • Grants are refused with clear error codes when the permission set does not exist yet or the boundary is missing.