# Product-access interface

**Version 1 · push only · `POST /v1/product-access/seat-allocations`**

What a customer account can actually use in your own application, sent to CommitLayer by your application's
backend. It is the second system of the [Commercial Account Changes pack](/docs/packs/commercial-account-changes):
an approved change is complete when billing shows it **and** the product shows it. A billing record, or a billing
event that tells your application to grant access, is never proof that the application did.

The interface is one narrow record shape. It is read-only by construction: nothing sent through it changes your
application, and CommitLayer never calls your application.

## The record

```http
POST /v1/product-access/seat-allocations
X-API-Key: <evidence key bound to product_access>
Content-Type: application/json

{
  "allocations": [
    {
      "account_ref": "org_8841",
      "seats": 40,
      "plan": "business",
      "effective_at": "2026-11-20T09:20:00Z",
      "observed_at": "2026-11-20T09:20:05Z"
    }
  ],
  "observed_through": "2026-11-20T09:30:00Z"
}
```

| Field | Required | Meaning |
|---|---|---|
| `account_ref` | yes | The account's id in your application. A commitment names the same value as `account.product_ref`; it is matched exactly and by nothing else. |
| `seats` | yes | How many seats the account can use. A whole number, zero or more. |
| `plan` | no | The plan the account is on, as your application names it. Compared only when the approved change names a plan. |
| `observed_at` | yes | When your backend read the allocation. |
| `effective_at` | no | When the allocation took effect: the moment the account could use this many seats. `observed_at` when omitted. Never after `observed_at`. It is **your application's own statement**: CommitLayer cannot check it, and it is the date the record is judged by. |
| `observed_through` | no | "Every allocation change up to this moment has been sent." The source's checkpoint: a change that is due is not called missing until the source has reported past its deadline. |

Every time is an ISO 8601 date and time with an offset from UTC (`2026-11-20T09:20:00Z`, `…+01:00`); anything else
is `422 invalid_timestamp`.

Each allocation is stored as a `product_access.seat_allocation` record on the account, dated at `effective_at`.
Up to 1,000 allocations a request. Sending the same allocation again is the same record. The answer is the
answer of `POST /v1/facts` (per record: stored or duplicate, the trust class it got, the actions it is about)
plus `interface: "product_access.v1"`. The full reference is in the [API reference](/docs/api#commitments).

## Who may send it

An **evidence key** bound to the source `product_access`, held by your application's backend and by nothing that
performs the work, and **attested** for that source by an Owner or Admin
(`POST /v1/evidence/attestations`). Only then are its records `backend_attested`, which is what the account-change
contract requires.

- A record sent by a key that also records actions is the performing side speaking for itself. It is stored, it is
  shown as not eligible, and it can neither satisfy a check nor hide the attested record a check reads.
- **No key can say which account a commitment is about.** A commitment's identity is the two links CommitLayer
  makes from the approved change (`account.billing_ref`, `account.product_ref`). An identity link that names the
  source `commitments`, or whose either end is a commitment's id, is refused on every evidence route
  (`403 commitment_identity_reserved`), for the performing side's key, for an evidence key bound to another
  source and for this source's own attested key alike, and the engine reads no other link for a commitment even
  if one were stored. So a record of another account can never be read as this commitment's, and the
  commitment's own links can never be taken over or detached.
- A record sent by an evidence key nobody attested does not count either. Until a key is attested, product access
  is "not supplied": a commitment that needs it reads **not verifiable**, never failed.
  `GET /v1/commitments/readiness` says so, and says who has to do what.
- A key bound to another source is refused (`403 source_not_allowed`).

## When to send

1. **On every change.** When an account's allocation changes, send the new allocation with `effective_at` set to
   the moment it changed. This is what lets CommitLayer tell a change made in time and seen late from a change
   made late.
2. **On a schedule, with `observed_through`.** A source that has said nothing since before a deadline has not been
   shown to be current. Declaring `observed_through` every few minutes (with or without allocations) says "nothing
   else changed up to here", which is what lets a change that never happened be called missing instead of
   unknown.
3. **After a correction.** Nothing special: the corrected allocation is a change like any other. CommitLayer reads
   it, evaluates the exception's resolution condition and records the correction.

If your application cannot say when an allocation took effect, send `observed_at` only. A change is then dated at
the read that saw it, so a change made before a deadline and read after it is read as late. Push on change to
avoid that.

## What is read from it

For a commitment, the latest eligible record for the exact `account_ref`, dated at or before the commitment's
deadline, must show the approved `seats` (and `plan`, when the approval names one). The commitment is decided at
its deadline, never before: a record that already shows the approved account seats is shown as provisional until
then. For 30 days after the deadline, a record that shows another number of account seats after a complete change
or after a verified correction opens an exception, unless a later approved change for the same account has taken
over.

Once a correction has been verified, or an exception accepted, the outcome at the deadline is frozen. A record
sent afterwards with an `effective_at` inside the deadline is kept as an event on the commitment and does not turn
a corrected change into one that was on time.

CommitLayer never reads your application. "Check again now" on a commitment checks against the records already
received; a fresh allocation has to be sent by your backend.

## Limits of this release

- **Push only.** There is no connector that reads an application, and none is promised here. Your backend sends
  the records.
- **Seats and a plan name.** Feature flags, usage limits, roles and per-user assignments are not part of the
  record.
- **One number per account.** An account with several seat pools is sent as the number the approved change is
  about.
- CommitLayer cannot check that the records are true to your application. The attestation is your statement that
  the key is held by the system of record and by nothing the agent can reach; that is why it is a person's,
  recorded and revocable.
