Register an app and enable it for a tenant

201. NO step-up, and that is proportionate: a new registry row grants nobody anything — the app is unreachable until a tenant enablement AND a per-member grant exist, so it is inert on arrival, unlike the deactivation in PATCH. An app is NOT an OAuth client: the app is the unit of access control (what azp names and what a grant grants), an OAuth client is a program that authenticates into it, and lookup.oauth_clients.client_app_id is the link — separate tables so an app gaining a second client does not mean migrating every grant and every projected row. 409 on a duplicate code, or on kind: 'identity' when an identity app already exists — and that refusal comes from the DATABASE (uq_client_apps_single_identity, a partial unique index mapped from 23505), not from the handler, because the cardinality of the /internal/validate exemption must not depend on a process reading its own copy of the rule. Sending isActive is a 422, not a silently ignored field.

Unpaged — the registry is platform configuration with a handful of rows — ordered by sortOrder then code. Deactivated apps are INCLUDED deliberately: an operator listing the registry is very often looking for exactly the row that has been switched off, so filtering it out would hide the answer to the question being asked. The tenant-facing drop-down (GET /v1/me/apps) does its own filtering to live product apps rather than relying on a default here.

PUT because a status is a state to ASSERT rather than a set of verbs: sending active twice is a no-op, and moving between states is one operation in both directions. The three statuses are not three shades of off — suspended DENIES access but RETAINS the projection (the app's domain data still foreign-keys to those rows), terminated denies and RETIRES it with a tombstone. Suspending never touches per-member grants: destroying state an operator would have to reconstruct by hand on restore would make it one-way in practice. Re-activating a TERMINATED enablement clears the backfill so the tenant is projected in full — the tombstone retired the app's copy, so returning is a fresh projection, not a resume. The identity app cannot be enabled → 422: membership alone governs access to it, so the row would be one scope() deliberately ignores. tenantId is a BODY field here and a QUERY param on the read, never a path segment (IAM-API-02 / REST-ROUTE-03) — the addressed resource is the enablement, not the tenant.

backfillOutstanding is the operational field: true means the chunker has not finished projecting this tenant into that app, so a member may legitimately be missing downstream. FALSE DOES NOT MEAN EVERY MEMBER IS PRESENT — anyone granted the app AFTER this backfill completed is not projected by anything, and re-running the resync below is what brings them in. It is the read that answers “is onboarding still in progress, or is something broken” — see scenario 42.

Clears backfilled_at and the keyset cursor so the chunker re-emits the whole (tenant, app) pair. Safe at any time and safe twice — every downstream upsert is version-guarded, so a re-emitted row at an equal or lower version is discarded. That is what makes it a legitimate FIRST response rather than a last resort: the cost is delivery work, and nothing already correct changes. 404 when there is no live enablement for the pair — silently succeeding would leave an operator believing a repair had run.

At least one mutable field is required (an empty body is 422). MUTABLE: label, description (an explicit null clears it), sortOrder, isActive, and isAutoEnabledOnRegister — the last opts the app into SELF-SERVICE SIGN-UP ENABLEMENT: when a POST /v1/auth/registration/complete carries a clientId naming an active product app with this flag on, that same transaction enables the new tenant for the app and grants the founder it, so the backfill projects the pair within one poll interval with no operator step (scenario 3). The SAME flag is what makes the app joinable by someone who ALREADY has an account (scenario 50) — both surfaces gate on the same four predicates, so switching it off closes both at once. It defaults FALSE because it bypasses the pay-first subscription flow. 🔐 Step-up is required ONLY to deactivate: isActive: false takes an app out of service for every tenant and every user at once, whereas a label fix cannot — gating the relabel too would train operators to keep a step-up factor to hand for routine work, which is how the control stops meaning anything. Re-activation is likewise ungated; restoring service is not the dangerous direction. To retire, send { isActive: false, stepUp: { password } }. The IDENTITY app can never be deactivated at any step-up level — it is the path to every account-recovery screen, including for the operator trying to undo the change. code and kind are NOT updatable → 422, not a silently ignored field: code is how runbooks and humans address an app while every row addresses it by id, and kind decides whether /internal/validate gates on a grant at all. An omitted field is unchanged; an explicit null description clears it. There is no DELETE — five tables reference an app ON DELETE RESTRICT and the projection ledger must outlive everything it points at.