AP2 mandate interop: reading a DueReason grant as an Agent Payments Protocol mandate
How a DueReason signed grant maps onto Google's Agent Payments Protocol (AP2) mandate shape, and the toAp2Mandate() translation the SDK ships today.
Updated · 6 min read
In short
- Google's Agent Payments Protocol (AP2) and a DueReason grant solve the same problem - prove an agent is authorized to do one specific, bounded thing - with the same building blocks: a signed, scoped, expiring token a verifier checks against a published key, not a password or a standing API credential.
- `toAp2Mandate` in `@duereason/sdk` is a pure, additive translation: it calls the existing `verifyGrant` first, and only once a grant verifies does it reshape the same claims onto AP2's mandate fields (issuer, credentialSubject.scope, proof).
- This is grant-format interop only: nothing about how DueReason issues or verifies a grant changes, no AP2 transport or wallet is implemented, and no payment rail is wired up. `mandate.proof` still points back at the original DueReason signature.
- Use it when something you don't control - a merchant, a payment processor, a Credential Provider - already speaks AP2 and needs to read a DueReason approval without learning DueReason's own grant format first.
An AI agent asking to spend money and an AI agent asking to deploy code need the same proof before anyone lets it proceed: not "this caller has a valid API key" but "a specific person approved exactly this action, for this amount or this target, before it expiration passed, and here is cryptographic evidence of who and when." DueReason has shipped that proof as a signed grant since its first release. Google's Agent Payments Protocol (AP2) ships a version of the same idea scoped to payments, as a public, versioned specification several merchants, wallets and payment processors are building against. toAp2Mandate in @duereason/sdk reads a DueReason grant and hands back the same authorization reshaped onto AP2's vocabulary, so a system that already understands AP2 mandates does not have to learn DueReason's claim names first.
What AP2 mandates look like
AP2 defines two mandate types travelling as SD-JWT verifiable credentials: a Checkout Mandate proving a Shopping Agent is authorized to buy a specific assembled checkout, and a Payment Mandate proving it is authorized to pay for one. Each names its schema version in a vct claim (mandate.payment.1 for a closed Payment Mandate, mandate.payment.open.1 for the user-signed open version that bounds an autonomous agent with constraints like an amount range or an allowed-payee list), carries a cnf key-binding claim when it authorizes an agent key rather than a human directly, and is always verified against a published key before anything in the payload is trusted - exactly the same order of operations verifyGrant already enforces for a DueReason grant.
What a DueReason grant already has
A DueReason grant is a compact JWS, Ed25519-signed, with claims iss (issuer), org (organization), act (the approved action key), sub (the approval request id), ph (the sha256 of the exact approved payload), apv (who approved it, in order), iat and exp. Every field AP2 cares about for verification - who issued it, what it scopes, when it expires, and a signature a verifier checks against a published key - is already there under DueReason's own names; toAp2Mandate is the mapping from one vocabulary to the other, not new cryptography.
The translation
Call const mandate = await toAp2Mandate({ grant, payload, organization: "acme", action: "payment" }) from @duereason/sdk; every field on the returned mandate is a direct, lossless copy of a grant claim:
Ap2Mandate field | From the grant |
|---|---|
issuer | iss |
issuanceDate / expirationDate | iat / exp, as ISO 8601 |
credentialSubject.id | jti |
credentialSubject.scope.organization | org |
credentialSubject.scope.action | act |
credentialSubject.scope.approvalRequestId | sub |
credentialSubject.scope.payloadHash | ph |
credentialSubject.scope.approvedBy | apv |
proof.jws | the original grant, unmodified |
toAp2Mandate calls verifyGrant first, with the same options and the same GrantVerificationError on anything that does not check out; a grant that fails verification never reaches the translation step. The resulting Ap2Mandate carries a type: ["VerifiableCredential", "Ap2Mandate"] and @context entries so a generic verifiable-credential reader recognizes the shape, but its proof references the original DueReason signature rather than minting a new one - an AP2-native verifier still has to fetch the referenced grant and verify it (directly, or via POST /api/v1/grants/verify) rather than trust the mandate shape on its own.
What this is not
This ships grant-format interop only. It does not implement any part of an AP2 transport (the Shopping Agent, Merchant, Credential Provider or Merchant Payment Processor roles), does not talk to a wallet or a payment network, and does not let DueReason issue a grant that is itself a valid, independently-signed AP2 mandate from day one - that would need AP2's own signing scheme (ES256 over an SD-JWT, not DueReason's EdDSA JWS) and is a deliberately separate, unbuilt decision. Nothing about how DueReason issues or verifies its own grants changes: verifyGrant is untouched, and every existing executor that checks a grant today keeps working exactly as before.
When to reach for it
Reach for toAp2Mandate when something outside your control already expects AP2's vocabulary - a merchant's checkout integration, a payment processor's verification step, a Credential Provider evaluating whether to hand over a payment credential - and you would otherwise have to explain DueReason's own grant claims to them first. If your own executor is the only thing checking the grant, there is nothing to gain from the translation: verify the grant directly, the way the grant verification guide describes.
Questions
- Does toAp2Mandate create a new, independently valid AP2 signature?
- No. The returned mandate's proof references the original DueReason grant signature; it does not mint a new signature over the AP2 shape. A verifier still has to fetch and check the referenced grant, the same way it always would.
- Does this integrate a payment rail, wallet or the AP2 transport?
- No. This is a pure, local translation function with no network calls of its own beyond the grant verification toAp2Mandate already performs. Talking to a Shopping Agent, Merchant, Credential Provider or Merchant Payment Processor is out of scope for this function.
- Does this change how DueReason issues or verifies grants?
- No. verifyGrant is unmodified; toAp2Mandate calls it unchanged and only reshapes claims once a grant has already verified. Every existing integration keeps working exactly as it did before this function existed.
- Can DueReason issue a grant as an AP2 mandate directly, instead of translating one afterward?
- Not today. That would require signing with AP2's own scheme (an SD-JWT, ES256) rather than DueReason's EdDSA JWS, and is a separate decision tracked against a concrete integration need rather than built speculatively.
Read the full grant and API reference
Every claim in a grant, the JWKS endpoint, and the toAp2Mandate export live in the API docs and the SDK README.
Read the API docsSources
- Agent Payments Protocol (AP2) specification
- AP2 Payment Mandate schema
- Agent Payments Protocol documentation site
- Google Cloud: Announcing Agent Payments Protocol (AP2)
This guide explains the regulation as we read it; it is not legal advice. Check the official text and your national law, which may add obligations.