Creating the genesis operator

Out-of-band (dev only — 403 unless APP_ENV=development). Stands in for the privileged migration / break-glass seed that does this in staging and production. One transaction writes three rows: the identity.users row (status pending_verification, password_hash NULL, has_mfa_enabled false), ONE active identity.operator_roles grant of iam-platform-admin with a 1-year expiry, and an operator_setup verification token (7-day TTL) holding only sha256(setupToken). Copy setupToken from the response now — nothing can read it back. role is optional (defaults to iam-platform-admin) and must NOT be platform_admin (IAM-ROLE-02) — a bad value surfaces as a foreign-key error on operator_roles.role, not a friendly 422. 409 (“user already exists — use /operator-setup-token instead”) means you are past genesis for that email: skip to the re-mint card below.

Out-of-band (dev only). Run this INSTEAD of the seed above when it returns 409 “user already exists — use /operator-setup-token instead”, or whenever a setup token expired (7 days) or was lost. It inserts a fresh operator_setup token for an existing, not-yet-activated account and returns the raw value; it does NOT create accounts. Send email OR userId — exactly one. Two caveats, because this is not the genesis path: (1) it grants NO role — if the account was not seeded by the genesis call it holds no operator_roles grant, so the final GET /v1/admin/operators will 403 until an existing admin grants one (scenario 34); (2) if the account is already active, accept-setup is spent and a new token is useless — just go straight to the login card. In production this stands in for the setup-token email that POST /v1/admin/operators sends.

Product endpoint — byte-for-byte the same in every environment. Pre-auth: the setup token IS the authorization (no bearer, no x-gateway-context). The password (≥ 12 chars) is argon2id-hashed and the TOTP secret is written in the SAME transaction, so the account can never be left half-provisioned. Save the returned provisioningUri (scan it into an authenticator app for a realistic setup). The account stays pending_verification — a password now exists but still cannot sign in. The token is verified but NOT consumed here: you need the same value again in step 4.

Out-of-band (dev only). Stands in for the authenticator app: it decrypts the stored TOTP secret server-side and computes the code, so it works on the pending, not-yet-confirmed secret written by accept-setup. Codes rotate every 30s — near a boundary take the next-window value rather than letting it expire mid-request.

Product endpoint, pre-auth. One transaction re-verifies the token is still live, confirms the TOTP code, sets has_mfa_enabled=true, flips status to active, and CONSUMES the setup token (terminal — any later reuse is 401). Store the returned recovery codes now: shown exactly once, stored only as SHA-256 hashes, never logged, and the only way back in if the authenticator is lost. A wrong code 401s and the account does NOT go live — activation and a working second factor are the same atomic act. The account is now active + MFA-enabled + holds the iam-platform-admin grant: exactly the conjunction login re-checks every attempt.

Product endpoint, pre-auth. Never returns an access token — MFA is mandatory for operators (IAM-MFA-01) — so this ALWAYS yields { mfaRequired, mfaToken }. Copy mfaToken into step 7. A uniform 401 invalid_credentials here means the enrolment confirm never completed, the password is wrong, or the account is not active; the response is deliberately identical for all three.

Out-of-band (dev only). Generate a NEW code rather than reusing the enrolment value — the 30-second window has almost certainly rolled, and the mfaToken only lives ~5 minutes, so run this immediately after login.

Product endpoint, pre-auth. This is where the operator session is created and the real credentials are minted: accessToken (aud: iam-platform, carries sid, roles NOT embedded) + a rotating refreshToken. data.accessToken is auto-captured as the active bearer for the verification call below and every other /v1/admin/* scenario. 401 means the mfaToken expired (~5 min) or the code is stale — redo login, then fetch a code immediately.

Product endpoint. A 200 with the operator list proves all three layers: Kong verified the operator access token and minted the x-gateway-context, the iam-platform-admin grant resolved live from identity.operator_roles (never from the token — AUTH-GUARD-01), and the route authorised. A 403 here means the context is fine but the grant is missing or expired (the seed's grant lasts 1 year). The doc's step 8 (POST /v1/dev/oob/gateway-token) is not needed in this tester: it exists to mint a context when calling IAM directly, and every request here goes through Kong.