Platform

Platform catalogue; tenant users can see only the version linked to their own agreement.

Records supplied terms without inventing a price. Money is optional integer minor units plus a supported ISO currency. SaaS supports monthly/annual subscriptions and optional allowances/rates. On-prem supports one-time/annual licence terms and cannot commit without a separately typed annual support/maintenance component. Add-ons and professional services remain separate components.

The source must be the active configured root and the target must already be configured but inactive. A distinct system administrator approves the resulting maker-checker request. Approval installs an irreversible write barrier for the source while it is still active; it does not switch keys or rewrap data. New subject and audit-anchor writes may therefore refuse during the deliberately short operator cutover. There is no cancel/unblock operation and this endpoint never authorizes physical root removal.

Distinguishes the expected approved-awaiting-key-switch phase from a runnable or blocked configuration. Dependency counts are tenant-scoped. Immutable historical identifier blind indexes and audit anchors normally keep `tenant_dependencies_clear` false, and every tenant would have to be assessed before a process-wide software root could even be considered for a separate retirement ceremony. This API always reports `physical_retirement_supported: false`.

Refuses until the approved target is active, the source remains configured, provider enumeration is complete and both key fingerprints still match approval. The worker authenticates and rewraps at most 100 subject-DEK envelopes per transaction, records immutable per-subject evidence, and transactionally enqueues the next page. It never decrypts or rewrites subject fields. Repeating this call while work is active is idempotent. It does not remove the source root.

Vendor control-plane read. It does not grant access to customer/AML records.

Links an immutable offer version to a tenant, with an explicit half-open term and IANA billing timezone. Selected components must belong to that exact offer; on-prem terms require selected annual support. This operation records commercial state only—it does not take payment, issue an invoice, enable a vendor feed or change tenant lifecycle.

Follows the closed lifecycle graph and appends an immutable revision. Past due and disputed are visible commercial states, never automatic AML suspension or quota gates.

Own-tenant, read-only view of the recorded agreement, immutable offer version, entitlement-only components, commercial status and usage evidence. Missing agreement or measurement is labelled unavailable rather than rendered as zero. A sanctions or adverse-media add-on is never proof that a provider feed is licensed or connected.

This is not an invoice or payment statement, and a past-due/disputed status does not suspend AML, screening or ingestion. Suspension remains the separate explicit tenant lifecycle operation.

**Your own tenant, unless you are a platform operator.** `tenancy.tenant.read` is a read of your own institution's record and returns exactly one row. Seeing the estate requires `tenancy.tenant.write`.

That distinction is a fix, not a nicety. This operation previously ran an unfiltered list inside a platform transaction and returned it to anybody holding `tenancy.tenant.read` — which the ng-core pack grants to `system_admin`, `executive` and `auditor`. Three of the seven BRD §4.1 personas could enumerate every other institution on the installation: slug, legal name, segment, data residency and status.

The estate view is resumable with `cursor`, keyed on (`created_at`, `id`). The single-tenant view returns exactly one row and carries no cursor, because a cursor on your own record would claim there is more of it.

The platform control plane. Creates the tenant in **`provisioning`**, never `active`: the authenticator refuses every request from a tenant that is not active, so a tenant left provisioning cannot serve traffic until a content pack has been installed and an administrator provisioned. Creating it active would open a door into an installation with no roles in it (Q11).

`slug` is the subdomain and cannot be changed afterwards — every IdP redirect URI and webhook callback binds to it, so renaming is a migration with a cutover rather than an edit.

Without `tenancy.tenant.write` a caller may read only their own tenant, and asking for another id returns the same `404` a non-existent id returns. A `403` would confirm the tenant exists, which is the fact being withheld.

Replaces display name, segment and residency together rather than patching single fields. A partial update over three columns needs three "was this key present" checks and the one that gets forgotten silently blanks a column — `data_residency` defaulting itself back to empty would put a tenant outside the BRD §9 residency check while looking like a rename.

Status is **not** settable here. See `POST /v1/tenants/{tenantID}/status`.

Its own operation rather than a field on the PATCH, because the blast radius is different in kind: a suspended tenant has **every** request refused by the authenticator with `tenant-inactive` from the moment this returns. An act with that reach should not be reachable by a form that also fixes a typo in the display name.

A `reason` is required for anything but a resume. The audit row is the only place the "why" survives, and "who suspended this bank, and why" is asked after the fact.

Returns measurements that have already been **recorded**, newest period first. A period nobody measured comes back absent, not zero: those are different facts, and conflating them reports a quiet month for a tenant whose measurement simply never ran.

These rows are usage evidence, not invoices or payments. Open rows may be corrected; closed rows name the IANA billing timezone and cannot be changed.

`POST`, not `GET`, because it **writes**. The snapshot is the fact; the query that produced it is not repeatable once retention has purged the source rows, so a live count would let a closed period's usage change retroactively or vanish.

The window is **half-open**: `[period_start, period_end)`. A closed range double-counts a transaction booked exactly at a boundary midnight into two months. Timestamps rather than dates, because `2026-08-01` is two different instants in Lagos and in UTC — an hour of a bank's transactions either side of an invoice line.

Re-measuring an open period corrects the recorded row in place rather than appending a second one and is refused after closure. Maximum window: one year. A daily run-on-start worker closes the previous local calendar month from the agreement's explicit IANA timezone; its half-open period key makes retries idempotent.