{"openapi":"3.1.0","info":{"title":"MandateShield Cryptographic Payment Authority API","version":"2.0.0","description":"Deterministic authorization control for autonomous AI-agent purchases. Call immediately before payment execution.","contact":{"name":"MandateShield","url":"https://mandateshield.com/docs"}},"servers":[{"url":"https://mandateshield.com"}],"tags":[{"name":"Pre-flight","description":"Evaluate a purchase against user-approved boundaries."}],"paths":{"/api/v1/preflight":{"options":{"operationId":"preflightOptions","summary":"Inspect CORS support","responses":{"204":{"description":"CORS pre-flight accepted"}}},"post":{"operationId":"evaluatePurchase","tags":["Pre-flight"],"summary":"Evaluate an autonomous purchase before payment","description":"Anonymous requests run in the limited sandbox. Bearer API keys enable persisted decisions, durable replay protection and production billing.","security":[{"bearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PurchaseEnvelope"},"examples":{"approvedRailTicket":{"summary":"Purchase inside an AP2 mandate","value":{"protocol":"AP2","mandate_id":"mnd_2048","agent_id":"agent_travel_07","merchant_id":"merchant_rail","amount":{"value":124.9,"currency":"USD"},"limits":{"max_amount":150,"currencies":["USD"],"merchants":["merchant_rail"]},"created_at":"2026-07-24T08:50:00Z","expires_at":"2026-07-24T19:00:00Z","idempotency_key":"order_9f22a1","intent_hash":"sha256:example","user_consent":true,"credential_binding":"tap:merchant_rail:agent_travel_07"}}}}}},"responses":{"200":{"description":"Decision completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreflightDecision"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"description":"API key is invalid or revoked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Production access is paused","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Duplicate or concurrent replay blocked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PreflightDecision"}}}},"413":{"description":"Request exceeds 100 KB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Sandbox rate or monthly limit reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/batch":{"post":{"operationId":"evaluatePurchaseBatch","tags":["Pre-flight"],"summary":"Evaluate up to 25 autonomous purchases","description":"Runs every envelope through the full pre-flight path, including per-item replay protection, evidence persistence and usage metering when authenticated.","security":[{"bearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["purchases"],"properties":{"purchases":{"type":"array","minItems":1,"maxItems":25,"items":{"$ref":"#/components/schemas/PurchaseEnvelope"}}}}}}},"responses":{"200":{"description":"Batch completed","content":{"application/json":{"schema":{"type":"object","required":["summary","results"],"properties":{"summary":{"type":"object","properties":{"total":{"type":"integer"},"allowed":{"type":"integer"},"reviewed":{"type":"integer"},"blocked":{"type":"integer"},"errors":{"type":"integer"}}},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"status":{"type":"integer"},"result":{"$ref":"#/components/schemas/PreflightDecision"}}}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/v2/verify":{"post":{"operationId":"verifyCryptographicAuthority","tags":["Pre-flight"],"summary":"Verify signed purchase authority and issue a portable receipt","description":"Fail-closed verification for compact JWS, AP2 SD-JWT and Visa TAP-style HTTP message signatures. Valid evidence continues through the deterministic v1 boundary; every decision is returned with a MandateShield-signed receipt.","security":[{"bearerAuth":[]},{}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["envelope","evidence"],"properties":{"envelope":{"$ref":"#/components/schemas/PurchaseEnvelope"},"evidence":{"$ref":"#/components/schemas/CryptographicEvidence"}}}}}},"responses":{"200":{"description":"Cryptographic decision completed","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PreflightDecision"},{"type":"object","required":["assurance","signed_receipt"],"properties":{"assurance":{"type":"object"},"signed_receipt":{"$ref":"#/components/schemas/SignedDecisionReceipt"}}}]}}}},"400":{"$ref":"#/components/responses/BadRequest"},"503":{"description":"A signed receipt could not be issued","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v2/receipts/verify":{"post":{"operationId":"verifyDecisionReceipt","tags":["Pre-flight"],"summary":"Verify a portable MandateShield decision receipt","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["compact"],"properties":{"compact":{"type":"string"}}}}}},"responses":{"200":{"description":"Receipt signature is valid"},"400":{"description":"Receipt is malformed or invalid"}}}},"/api/v1/threat-intelligence":{"get":{"operationId":"getThreatIntelligence","tags":["Pre-flight"],"summary":"Get privacy-thresholded cross-account threat trends","description":"Returns only protocol and reason-code aggregates observed by at least three independent accounts. Raw merchant identifiers and account identities are never published.","responses":{"200":{"description":"Threat-intelligence snapshot"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"ms_test_… or ms_live_…"}},"schemas":{"PurchaseEnvelope":{"type":"object","additionalProperties":true,"required":["protocol","mandate_id","agent_id","merchant_id","amount","limits","expires_at","idempotency_key","user_consent"],"properties":{"protocol":{"type":"string","enum":["AP2","TAP","UCP","X402","ACP","CUSTOM"]},"mandate_id":{"type":"string","minLength":1},"agent_id":{"type":"string","minLength":1},"merchant_id":{"type":"string","minLength":1},"amount":{"type":"object","required":["value","currency"],"properties":{"value":{"type":"number","exclusiveMinimum":0},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$","description":"ISO 4217 currency code"}}},"limits":{"type":"object","required":["max_amount","currencies","merchants"],"properties":{"max_amount":{"type":"number","exclusiveMinimum":0},"currencies":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{3}$"}},"merchants":{"type":"array","items":{"type":"string","minLength":1}}}},"created_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"idempotency_key":{"type":"string","minLength":1},"intent_hash":{"type":"string"},"user_consent":{"type":"boolean"},"credential_binding":{"type":"string"},"purpose":{"type":"string"}}},"CryptographicEvidence":{"type":"object","required":["format","public_key"],"properties":{"format":{"type":"string","enum":["jws","sd-jwt","http-message-signature"]},"compact":{"type":"string"},"public_key":{"type":"object"},"expected_audience":{"type":"string"},"expected_nonce":{"type":"string"},"expected_authority":{"type":"string"},"algorithm":{"type":"string","enum":["ES256","EdDSA","RS256","PS256"]},"signature":{"type":"string"},"signature_input":{"type":"object"},"components":{"type":"object"}}},"SignedDecisionReceipt":{"type":"object","required":["format","compact","receipt_id","key_id","jwks_uri","verify_uri"],"properties":{"format":{"const":"application/mandateshield-receipt+jwt"},"compact":{"type":"string"},"receipt_id":{"type":"string"},"key_id":{"type":"string"},"jwks_uri":{"const":"https://mandateshield.com/.well-known/jwks.json"},"verify_uri":{"const":"https://mandateshield.com/api/v2/receipts/verify"}}},"Finding":{"type":"object","required":["code","message","severity"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"severity":{"type":"string","enum":["high","medium","low"]}}},"PreflightDecision":{"type":"object","required":["decision","score","receipt","checked_at","protocol","findings","risk","recommended_action","controls"],"properties":{"decision":{"type":"string","enum":["ALLOW","REVIEW","BLOCK"]},"score":{"type":"integer","minimum":0,"maximum":100},"receipt":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"checked_at":{"type":"string","format":"date-time"},"protocol":{"type":"string"},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"risk":{"type":"object","required":["level","requested_value","mandate_headroom","blocked_value","primary_reason"],"properties":{"level":{"type":"string","enum":["CLEAR","GUARDED","ELEVATED","CRITICAL"]},"requested_value":{"type":["number","null"]},"mandate_headroom":{"type":["number","null"]},"blocked_value":{"type":"number","minimum":0},"primary_reason":{"type":["string","null"]}}},"recommended_action":{"type":"string"},"controls":{"type":"object","required":["evaluated","passed"],"properties":{"evaluated":{"type":"integer","minimum":0},"passed":{"type":"integer","minimum":0}}},"mode":{"type":"string","enum":["sandbox","test","live"]},"persisted":{"type":"boolean"}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Invalid JSON or purchase envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}