Product-access interface
The one record shape your application's backend sends for what an account can use (seats, plan, when it took effect): who may send it, when, and what is read from it. Push only.
Last changed Markdown versionllms.txt
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: 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
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.
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 sourcecommitments, 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/readinesssays so, and says who has to do what. - A key bound to another source is refused (
403 source_not_allowed).
When to send
- On every change. When an account's allocation changes, send the new allocation with
effective_atset to the moment it changed. This is what lets CommitLayer tell a change made in time and seen late from a change made late. - On a schedule, with
observed_through. A source that has said nothing since before a deadline has not been shown to be current. Declaringobserved_throughevery 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. - 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.