Skip to content

Mandate specification

Status

Draft v0, implemented in version 0.2.0 of the library. The source is docs/spec-mandate.md in the repository (in Spanish).

A mandate is a verifiable credential (SD-JWT) that authorizes an agent to spend within limits. It maps to AP2 v0.2; whatever AP2 does not cover goes into claims prefixed with ritta:.

Required claims

Names are literal and flat: ritta:limits.total is a single claim, not a nested object.

Claim Type Meaning
iss DID or URL Who authorizes (person or company). Currently did:<method>:... or https://... is accepted
sub string Identifier of the authorized agent
ritta:limits.total int Total authorized amount, in the smallest unit (> 0)
ritta:limits.per_operation int Per-operation cap (> 0 and ≤ total)
ritta:limits.currency string ISO 4217 (ARS, BRL) or token (USDC). Syntax: ^[A-Z][A-Z0-9]{2,9}$
ritta:scope.merchants list Allowed merchant IDs (empty = any, discouraged)
ritta:scope.categories list Allowed categories (empty = any, discouraged)
ritta:hitl_threshold int Amount from which human approval is required (≥ 0)
exp timestamp Expiration (NumericDate, UTC seconds)
jti string Unique nonce (anti-replay)
ritta:state open / closed Open (budget) or closed (tied to a checkout)

Amounts are JSON integers. A number with decimals (even 100.0) or a string makes the mandate malformed.

Compatibility

Version 0.1.0 used a different prefix. Since 0.2.0 the prefix is ritta:, and a 0.2.0 verifier does not accept mandates with the old prefix: it rejects them as malformed because the required claims are missing. No migration is offered because 0.1.0 had no external users.

Format (SD-JWT)

The signed mandate is an SD-JWT in compact form:

<JWT signed by the issuer>~
  • Header: {"alg": "EdDSA", "typ": "vc+sd-jwt"}. Ed25519 signature.
  • Payload: "_sd_alg": "sha-256" plus the claims in the table.
  • The trailing ~ is the SD-JWT separator, with zero disclosures and no Key Binding JWT.

The current version has no selective disclosure: every claim is visible. The format is already valid SD-JWT, so adding disclosures later does not break the envelope. Meanwhile, the verifier rejects as malformed any token with disclosures, a Key Binding JWT, _sd digests, a header with crit, duplicate JSON members or non-canonical base64url.

Verification

verify(token, public_key, *, amount, merchant, category, remaining, now=None)

Returns ok only if all of these hold:

  • the signature is valid;
  • now < exp;
  • amount <= per_operation;
  • amount <= remaining;
  • merchant is in scope;
  • category is in scope.

It is pure: no network calls. The remaining balance is supplied by the gateway (ledger); the library receives the value.

Order of rejection reasons

On failure, it returns the first reason in this order:

Order Reason
1 malformed / invalid_signature
2 expired
3 amount_over_per_operation
4 amount_over_remaining
5 merchant_not_allowed
6 category_not_allowed
  • amount and remaining are integers in the smallest unit of the mandate currency. Invalid arguments (amount <= 0, remaining < 0, non-integers, a timezone-naive now) are programming errors and raise an exception.
  • verify does not enforce hitl_threshold: asking for human approval is a gateway policy decision.

Open questions

Not yet decided:

  • Exact iss format for Argentine small businesses without a DID (gateway did:web + CUIT?).
  • Mapping of ritta:scope.categories to card MCC codes.
  • typ: the current SD-JWT VC draft uses dc+sd-jwt (formerly vc+sd-jwt) and requires the vct claim. Still to confirm what AP2 v0.2 verifiers expect.
  • closed mandate: which claim ties it to the checkout (AP2 CartMandate). Today it is verified the same as an open one.
  • Agent binding (holder binding, cnf claim + Key Binding JWT): not implemented.