Skip to content
Browse the documentation
Reference

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 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.