Skip to main content

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 opaque subject_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 is SINGLE_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_MONTH snaps to the first of the month, ANCHORED_MONTH keeps the anchor’s day, and FIXED_DAYS is a fixed day count.
  • period_days: required only for FIXED_DAYS.
  • valid_from is the anchor for ANCHORED_MONTH; there is no separate anchor field in the request. Evidence carries the derived period_anchor.
  • period_count: the number of periods the term covers.
  • period_max_amount and period_currency: the most that may be reserved in any one period, in minor units.
  • valid_until must be exactly the end of the final period, and the whole term may not exceed 400 days.
A complete request for three 30-day periods, each capped at EUR 500.00:
The create response is the Mandate, starting in PENDING_APPROVAL:
The full object, including 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:
The response also carries 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 RESERVED is denied with MANDATE_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_USE Mandate; a RECURRING Mandate stays ACTIVE until its term ends.
  • can_execute is true only for an unexpired ALLOW reservation.
Disable any external credential before cancelling or revoking. Attesso records your assertion but cannot disable cards, tokens, provider jobs, or bookings.

Complete an authorization

Implement execution gating, commit, cancellation, and retries.