Mandates
A Mandate is an immutable statement of what one authenticated end user approved. If the authority changes, create and approve a new Mandate rather than mutating the old one. Every Mandate contains an opaquesubject_reference, one policy, an approval deadline, and a validity window. A single-use term runs up to 30 days. A recurring term is exactly its period schedule, up to 400 days.
CONSUMED, REVOKED, and EXPIRED are terminal.
Execution modes
A Mandate isSINGLE_USE or RECURRING.
A recurring Mandate names its cadence with
period_unit and period_count; each period’s spend is capped by period_max_amount in period_currency. The period a charge is attributed to is chosen at reservation time and recorded on the Authorization as period_index. Period terms are part of the approved authority; an execution whose terms no longer match the approved terms is denied.
Recurring terms
period_unit:CALENDAR_MONTHsnaps to the first of the month,ANCHORED_MONTHkeeps the anchor’s day, andFIXED_DAYSis a fixed day count.period_days: required only forFIXED_DAYS.valid_fromis the anchor forANCHORED_MONTH; there is no separate anchor field in the request. Evidence carries the derivedperiod_anchor.period_count: the number of periods the term covers.period_max_amountandperiod_currency: the most that may be reserved in any one period, in minor units.valid_untilmust be exactly the end of the final period, and the whole term may not exceed 400 days.
PENDING_APPROVAL:
policy, policy_digest, and current_period once active, is shown under Period usage.
A SINGLE_USE Mandate sends the same body without execution_mode and the period fields.
Each purchase is checked against the policy cap and the remaining budget of its period. A charge that would push a period past period_max_amount is denied with PERIOD_LIMIT_EXCEEDED; the next period starts with its own budget when its time arrives.
Period usage
GET /v1/mandates/{id} reports current_period for an ACTIVE recurring Mandate:
The field is present only while the Mandate is
ACTIVE and inside its term. A period nobody has charged in reports zero consumed and the full limit.
A read of an active monthly Mandate after one 120.00 charge is committed:
subject_reference, policy, policy_digest, approval_deadline, version, created_at, and updated_at.
Authorizations
An Authorization is the durable result of evaluating one proposed action. Every structurally valid evaluation creates one, including non-allow results.
An
ALLOW starts in RESERVED. It may become COMMITTED, CANCELLED, or EXPIRED. Non-allow decisions use terminal DENIED or INDETERMINATE states.
One reservation at a time
- A Mandate may evaluate many candidates but can have only one active reservation.
- A second authorization while one is
RESERVEDis denied withMANDATE_UNAVAILABLE; it creates no reservation. - Concurrent eligible requests cannot both reserve it.
- Cancellation or reservation expiry permits a later eligible attempt.
- Commit permanently consumes a
SINGLE_USEMandate; aRECURRINGMandate staysACTIVEuntil its term ends. can_executeis true only for an unexpiredALLOWreservation.
Complete an authorization
Implement execution gating, commit, cancellation, and retries.

