VENDOR SPECIFICATION · V1

A signed permit is not spent until the online state says so.

MandateShield Execution Permit v1 binds one short-lived authorization to one exact provider request, payee, amount, resource and PROCESSOR audience.

TOKEN PROFILE

ES256, MSP+JWT and a maximum 60-second lifetime

The permit is a compact JWT signed with ES256. Its protected header must contain typ=MSP+JWT, alg=ES256 and exactly one retained MandateShield JWKS kid. The aud claim is one exact string, never an audience array. Validators must reject a permit whose exp is more than 60 seconds after iat, whose time window is not currently valid or whose settlement deadline has already closed.

Public verification keys are published at /.well-known/jwks.json. Key retention permits later signature inspection, but does not recreate online redemption state.

EXACT REQUEST BINDING

Changing one execution fact invalidates the permit

The claims bind the authorization and decision receipt, input and attempt digests, protocol, provider profile, environment, account, provider request and idempotency key. They also bind the canonical payee destination, exact fiat minor units or atomic-asset amount, and the HTTPS method, URI and body digest. max_uses=1 and scope=payment:execute:one are fixed values, not caller-selectable permissions. The signed one_use_enforced=false claim is deliberate: the offline token cannot know whether its one use remains available. Only the online redemption can establish that fact.

// Protected header
{
  "alg": "ES256",
  "typ": "MSP+JWT",
  "kid": "ms-receipt-key-2026-07"
}

// Decoded claims
{
  "iss": "https://mandateshield.com",
  "aud": "https://gateway.example/payments",
  "jti": "permit_019f98d5d1d84abbbd12e0781976b3a1",
  "iat": 1785024000,
  "nbf": 1785024000,
  "exp": 1785024060,
  "spec": "https://mandateshield.com/specifications/execution-permit/v1",
  "permit_profile": "provider-bound-execution-v1",
  "scope": "payment:execute:one",
  "authorization_ref": "execauth_019f98d5d1d84abbbd12e0781976b3a1",
  "decision_receipt_id": "msr_019f98d5d1d84abbbd12e0781976b3a1",
  "decision_receipt_hash": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "input_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "attempt_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "protocol": "X402",
  "provider": {
    "profile": "X402_V2_EXACT",
    "environment": "live",
    "account": "0x1111111111111111111111111111111111111111",
    "request_id": "resource-attempt-01",
    "request_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "idempotency_key": "provider-submit-attempt-01"
  },
  "payee": {
    "merchant_id": "merchant_data_api",
    "destination": "merchant_data_api",
    "destination_digest": "sha256:43f57269158d3cfa6fafe4ee76322b2293408bd4294b207b20d9e78b3dd8fb21"
  },
  "amount": {
    "mode": "ATOMIC_ASSET",
    "atomic_units": "1250000",
    "asset_decimals": 6,
    "asset_id": "0x2222222222222222222222222222222222222222",
    "network": "eip155:8453"
  },
  "resource": {
    "method": "GET",
    "uri": "https://api.example/reports/quarterly",
    "body_digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
  },
  "settlement_deadline": 1785024900,
  "max_uses": 1,
  "redemption_uri": "https://mandateshield.com/api/v2/execution-permits/redeem",
  "one_use_enforced": false
}

Execution Permit JWT Claims JSON Schema

ONLINE REDEMPTION

Only ISSUED → CLAIMED can unlock one submission

The trusted gateway sends the compact permit to POST /api/v2/execution-permits/redeem with a PROCESSOR bearer credential whose registered audience exactly equals the permit's string aud. MandateShield validates the signature, bindings, current time, credential scope and audience, then performs one atomic state transition.

  • A fresh ISSUED → CLAIMED transition returns state=CLAIMED and provider_submission_permitted=true.
  • Every replay observes state=CLAIMED and returns provider_submission_permitted=false.
  • An expired, invalid, wrong-audience or mismatched permit never grants submission.

OFFLINE LIMIT

Signature validity never proves one-use availability

An offline verifier can validate ES256, kid, issuer, exact audience, time and request bindings. It cannot observe the authoritative ISSUED or CLAIMED state, prove that another process has not already redeemed the token, or evaluate server-side revocation. Offline verification must always return a non-executable result and must never set provider_submission_permitted=true.

ENFORCEMENT CLASS

A permit creates integration infrastructure—not a provider mandate

Publishing and redeeming this permit does not prove that any payment provider currently requires MandateShield. FACILITATOR_ENFORCED applies only when an identified facilitator verifies and redeems the permit and refuses a request without it. PROVIDER_ENFORCED remains a future class until the payment provider itself makes successful redemption a mandatory authorization condition.

Continue to the terminal Execution Receipt specification