{
  "openapi": "3.1.0",
  "info": {
    "title": "Verihop Partner Sessions API",
    "version": "1.0.0",
    "description": "Source-validated application contract for five partner operations only. Server-side partner keys. Canonical governed-field input profile; legacy-only field tokens, query result-token compatibility, mobile/Portal/Backoffice/protocol routes, callbacks as webhooks, provider/device behavior and CORS/OPTIONS and managed gateway/WAF failures are outside this contract. Local source validation does not qualify production, a real partner, issuer authentication or a Store release. No automatic retry of a consuming result exchange. SLO alerts remain disabled."
  },
  "servers": [
    {
      "url": "https://api.verihop.com"
    }
  ],
  "externalDocs": {
    "description": "Canonical integration, acceptance and recovery guidance",
    "url": "https://www.verihop.com/devs"
  },
  "x-source-baseline": "491de71e8897dfbbb806f8e59b88539d7dbb3979",
  "x-validation": {
    "test": "verifybox-api/test/partner-openapi-contract.test.mjs",
    "declaredScope": "Application JSON responses and canonical public input. Policy/normalization/relational constraints described in prose are covered by handler regressions; JSON Schema does not grant approval or implement those policies."
  },
  "paths": {
    "/v1/sessions": {
      "post": {
        "operationId": "createSession",
        "summary": "Create a partner verification Session",
        "x-source": "verifybox-api/lib/session-api.mjs#handlePostSessions",
        "security": [
          {
            "PartnerApiKey": []
          }
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/CreateSession401"
          },
          "403": {
            "$ref": "#/components/responses/CreateSession403"
          },
          "413": {
            "$ref": "#/components/responses/CreateSession413"
          },
          "500": {
            "$ref": "#/components/responses/CreateSession500"
          },
          "400": {
            "$ref": "#/components/responses/CreateSession400"
          },
          "409": {
            "$ref": "#/components/responses/CreateSession409"
          },
          "410": {
            "$ref": "#/components/responses/CreateSession410"
          },
          "415": {
            "$ref": "#/components/responses/CreateSession415"
          },
          "429": {
            "$ref": "#/components/responses/CreateSession429"
          },
          "201": {
            "$ref": "#/components/responses/CreateSession201"
          },
          "200": {
            "$ref": "#/components/responses/CreateSession200"
          }
        },
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9._:-]{1,128}$"
            },
            "description": "Recommended UUID. Retain for the same logical payload/environment. Unknown outcome stays pending; do not rotate to bypass it."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SessionCreate"
              },
              "examples": {
                "Test": {
                  "summary": "Test-key canonical Personal Details request",
                  "value": {
                    "app": "RideNow",
                    "header": "Age check",
                    "fields": [
                      "legalName",
                      "over18"
                    ],
                    "callback": "https://partner.example/verihop/callback"
                  }
                },
                "ApprovedLivePilot": {
                  "summary": "Fictional approved Live pilot; example values grant no approval",
                  "value": {
                    "app": "Partner App",
                    "header": "Approved pilot age check",
                    "fields": [
                      "over18",
                      "idCard",
                      "passport"
                    ],
                    "allowedDocuments": [
                      "idCard",
                      "passport"
                    ],
                    "callback": "https://partner.example/verified",
                    "assurance_profile": "nfc_holder_match_pilot_v1",
                    "risk_context": {
                      "use_case": "rental",
                      "transaction_value_minor": 15000,
                      "currency": "EUR",
                      "consequential_decision": false
                    }
                  }
                }
              }
            }
          }
        },
        "description": "Server-side only. Active/Test/review-pending eligibility and key environment apply; legacy untagged keys retain source compatibility. Pilot, callback and field approvals remain mandatory where configured. An exact completed replay consumes no extra quota; uncertain writes must be reconciled."
      }
    },
    "/v1/sessions/{id}": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "minLength": 1
          }
        }
      ],
      "get": {
        "operationId": "getSession",
        "summary": "Read a Session status",
        "x-source": "verifybox-api/lib/session-api.mjs#handleGetSession",
        "security": [
          {
            "PartnerApiKey": []
          }
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/CreateSession401"
          },
          "403": {
            "$ref": "#/components/responses/GetSession403"
          },
          "413": {
            "$ref": "#/components/responses/CreateSession413"
          },
          "500": {
            "$ref": "#/components/responses/CreateSession500"
          },
          "400": {
            "$ref": "#/components/responses/GetSession400"
          },
          "404": {
            "$ref": "#/components/responses/GetSession404"
          },
          "200": {
            "$ref": "#/components/responses/GetSession200"
          }
        }
      }
    },
    "/v1/sessions/{id}/result": {
      "parameters": [
        {
          "name": "id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "minLength": 1
          }
        }
      ],
      "get": {
        "operationId": "consumeSessionResult",
        "summary": "Consume a private Session result once",
        "x-source": "verifybox-api/lib/session-api.mjs#handleGetResult",
        "security": [
          {
            "PartnerApiKey": [],
            "ResultToken": []
          }
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/ConsumeSessionResult401"
          },
          "403": {
            "$ref": "#/components/responses/ConsumeSessionResult403"
          },
          "413": {
            "$ref": "#/components/responses/CreateSession413"
          },
          "500": {
            "$ref": "#/components/responses/CreateSession500"
          },
          "400": {
            "$ref": "#/components/responses/ConsumeSessionResult400"
          },
          "404": {
            "$ref": "#/components/responses/ConsumeSessionResult404"
          },
          "409": {
            "$ref": "#/components/responses/ConsumeSessionResult409"
          },
          "410": {
            "$ref": "#/components/responses/ConsumeSessionResult410"
          },
          "503": {
            "$ref": "#/components/responses/ConsumeSessionResult503"
          },
          "200": {
            "$ref": "#/components/responses/ConsumeSessionResult200"
          }
        },
        "description": "Require now < min(Session.expires_at, result_token_expires_at), correct tenant/environment and an unconsumed token. Use the header. Disabled-by-default legacy query-token compatibility is deliberately not a supported new-integration transport.",
        "x-retry-policy": "never-automatically-retry"
      }
    },
    "/v1/document-receipts/{receipt_id}": {
      "parameters": [
        {
          "name": "receipt_id",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string",
            "minLength": 1
          }
        }
      ],
      "get": {
        "operationId": "getDocumentReceipt",
        "summary": "Retrieve one historical Document Receipt",
        "x-source": "verifybox-api/lib/document-receipt-api.mjs#handleGetDocumentReceipt",
        "security": [
          {
            "PartnerApiKey": []
          }
        ],
        "responses": {
          "401": {
            "$ref": "#/components/responses/CreateSession401"
          },
          "403": {
            "$ref": "#/components/responses/GetSession403"
          },
          "413": {
            "$ref": "#/components/responses/CreateSession413"
          },
          "500": {
            "$ref": "#/components/responses/CreateSession500"
          },
          "400": {
            "$ref": "#/components/responses/GetDocumentReceipt400"
          },
          "404": {
            "$ref": "#/components/responses/GetDocumentReceipt404"
          },
          "409": {
            "$ref": "#/components/responses/GetDocumentReceipt409"
          },
          "410": {
            "$ref": "#/components/responses/GetDocumentReceipt410"
          },
          "423": {
            "$ref": "#/components/responses/GetDocumentReceipt423"
          },
          "503": {
            "$ref": "#/components/responses/GetDocumentReceipt503"
          },
          "200": {
            "$ref": "#/components/responses/GetDocumentReceipt200"
          }
        }
      }
    },
    "/.well-known/jwks.json": {
      "get": {
        "operationId": "getJwks",
        "summary": "Discover public verification keys",
        "x-source": "verifybox-api/lib/lambda-system-api.mjs#handleGetJwks",
        "security": [],
        "responses": {
          "400": {
            "$ref": "#/components/responses/GetSession400"
          },
          "413": {
            "$ref": "#/components/responses/CreateSession413"
          },
          "500": {
            "$ref": "#/components/responses/CreateSession500"
          },
          "200": {
            "$ref": "#/components/responses/GetJwks200"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "PartnerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "Opaque partner API key; kept only on the partner backend. Not a JWT. Account/key/Session environment eligibility is checked server-side."
      },
      "ResultToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Result-Token",
        "description": "One-use callback result token; required together with PartnerApiKey."
      }
    },
    "schemas": {
      "LiveFieldToken": {
        "type": "string",
        "enum": [
          "legalName",
          "dateOfBirth",
          "over18",
          "over21",
          "passport",
          "idCard",
          "driverLicense",
          "residencePermit",
          "documentNumber",
          "documentExpiry",
          "documentCountry",
          "documentNationality"
        ],
        "description": "Current governed public fields. Compatibility-only tokens are outside this published input profile."
      },
      "DocumentType": {
        "type": "string",
        "enum": [
          "passport",
          "idCard",
          "driverLicense",
          "residencePermit"
        ]
      },
      "ReceiptId": {
        "type": "string",
        "pattern": "^dr_[A-Za-z0-9_-]{24}$"
      },
      "RiskContext": {
        "type": "object",
        "properties": {
          "use_case": {
            "type": "string",
            "description": "Trimmed and truncated to 64 characters, then must match ^[a-z][a-z0-9_:-]{0,63}$. Approved Live policy applies allowed_use_cases membership only when that list is nonempty; legacy empty lists skip membership. This compatibility behavior is not approval evidence. Establish the approved scope before external activation."
          },
          "transaction_value_minor": {
            "type": [
              "integer",
              "null"
            ],
            "minimum": 0,
            "maximum": 9007199254740991,
            "description": "Minor currency units. A non-null amount requires a normalized three-letter currency. Approved Live pilot policy requires a configured threshold: equality is accepted and values above it are rejected. Synthetic Test policy skips use-case/amount admission; Test success does not qualify Live."
          },
          "currency": {
            "type": [
              "string",
              "null"
            ],
            "description": "Trimmed, truncated to three characters, uppercased. Requires a non-null amount; with an amount the normalized value must match ^[A-Z]{3}$."
          },
          "consequential_decision": {
            "type": "boolean",
            "description": "A true value is rejected for the controlled pilot."
          }
        },
        "required": [
          "use_case",
          "consequential_decision"
        ],
        "additionalProperties": false
      },
      "SessionCreate": {
        "type": "object",
        "properties": {
          "app": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional display name: trimmed and truncated to 80 characters; blank nonempty input is rejected. Omission/null/empty string can use the customer default."
          },
          "header": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional title: trimmed and truncated to 120 characters; blank nonempty input is rejected. Omission/null/empty string can use the customer default."
          },
          "fields": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/LiveFieldToken"
            },
            "maxItems": 64,
            "description": "Omitted/null/empty remains an empty list; no default Personal Details. Required document types combine with AND. Duplicates are accepted; each field must also be customer-approved."
          },
          "callback": {
            "type": [
              "string",
              "null"
            ],
            "description": "Server-owned callback URL, trimmed/truncated to 2048 characters. Required when REQUIRE_SESSION_CALLBACK is true. Must have a host, no userinfo, and a permitted protocol (never javascript/data/file). Exact origin or hostname must be approved when callback allowlist policy applies. Prefer HTTPS partner backend; approved native schemes remain compatible."
          },
          "allowedDocuments": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "$ref": "#/components/schemas/DocumentType"
            },
            "minItems": 1,
            "maxItems": 4,
            "description": "Omitted/null means unrestricted. OR eligibility restriction; duplicates normalize to canonical order. Must include required document types. Driver-licence-only evidence cannot satisfy documentNationality."
          },
          "assurance_profile": {
            "type": [
              "string",
              "null"
            ],
            "description": "Trimmed/truncated to 64 characters and validated against nfc_holder_high_v1 or nfc_holder_match_pilot_v1. Omitted Test defaults to the pilot; omitted Live NFC selects the stronger high profile. Creation is not qualification."
          },
          "risk_context": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/RiskContext"
              },
              {
                "type": "null"
              }
            ],
            "description": "Required for explicit nfc_holder_match_pilot_v1. Live customer approval and accepted restrictions apply; nonempty approved use-case lists and configured amount thresholds are evaluated independently. Test policy bypasses use-case/amount admission, but still rejects consequential decisions. No schema or creation response grants Live approval."
          }
        },
        "required": [],
        "additionalProperties": true,
        "description": "Canonical public governed-field input profile. Unknown top-level members are ignored by current source; this schema permits them for compatibility. It does not grant field, callback or pilot approval."
      },
      "SessionCreated": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string"
          },
          "expires_at": {
            "type": "integer",
            "description": "Absolute Unix-second deadline; source TTL default 900, clamped 60–3600 seconds. Returned value is authoritative."
          },
          "launch_url": {
            "type": "string",
            "description": "Opaque returned HTTPS URL; open unchanged."
          },
          "app_clip_url": {
            "type": "string",
            "description": "Opaque returned native iOS App Clip URL; open unchanged."
          },
          "qr_url": {
            "type": "string",
            "description": "Currently equals launch_url."
          },
          "status_url": {
            "type": "string"
          }
        },
        "required": [
          "session_id",
          "expires_at",
          "launch_url",
          "app_clip_url",
          "qr_url",
          "status_url"
        ],
        "additionalProperties": false
      },
      "SessionStatus": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "description": "Stored status or derived expired; used can coexist with last_status success. Do not assume a closed enum for retained records."
          },
          "issued_at": {
            "type": [
              "number",
              "null"
            ]
          },
          "expires_at": {
            "type": [
              "number",
              "null"
            ]
          },
          "last_status": {
            "description": "Stored legacy JSON value or null; current writers use a status string."
          },
          "last_status_at": {
            "description": "Stored legacy JSON value or null; current writers use a timestamp."
          },
          "opened_at": {
            "type": [
              "string",
              "null"
            ]
          },
          "result_available": {
            "type": "boolean",
            "description": "Stored payload/token presence only; can remain true after consumption or expiry."
          },
          "result_token_expires_at": {
            "type": [
              "number",
              "null"
            ]
          },
          "result_token": {
            "type": "string",
            "description": "Only returned when both key and stored Session are explicitly Test; never use presence as proof of unconsumed authority."
          }
        },
        "required": [
          "session_id",
          "status",
          "issued_at",
          "expires_at",
          "last_status",
          "last_status_at",
          "opened_at",
          "result_available",
          "result_token_expires_at"
        ],
        "additionalProperties": false
      },
      "PersonalDetails": {
        "type": "object",
        "properties": {
          "legalName": {
            "description": "Only returned if requested and stored. Legacy stored JSON values retain their type; Test mode uses XXXTEST_USERXXX. No boolean/date/string type guarantee is imposed by the result handler."
          },
          "dateOfBirth": {
            "description": "Only returned if requested and stored. Legacy stored JSON values retain their type; Test mode uses XXXTEST_USERXXX. No boolean/date/string type guarantee is imposed by the result handler."
          },
          "over18": {
            "description": "Only returned if requested and stored. Legacy stored JSON values retain their type; Test mode uses XXXTEST_USERXXX. No boolean/date/string type guarantee is imposed by the result handler."
          },
          "over21": {
            "description": "Only returned if requested and stored. Legacy stored JSON values retain their type; Test mode uses XXXTEST_USERXXX. No boolean/date/string type guarantee is imposed by the result handler."
          }
        },
        "required": [],
        "additionalProperties": false
      },
      "DocumentDetails": {
        "type": "object",
        "properties": {
          "documentNumber": {
            "type": "string",
            "maxLength": 256,
            "minLength": 1,
            "pattern": "^[^\\u0000-\\u001f]+$"
          },
          "documentExpiry": {
            "type": "string",
            "maxLength": 256,
            "minLength": 1,
            "pattern": "^[^\\u0000-\\u001f]+$"
          },
          "documentCountry": {
            "type": "string",
            "maxLength": 256,
            "minLength": 1,
            "pattern": "^[^\\u0000-\\u001f]+$"
          },
          "documentNationality": {
            "type": "string",
            "maxLength": 256,
            "minLength": 1,
            "pattern": "^[^\\u0000-\\u001f]+$"
          }
        },
        "required": [],
        "additionalProperties": false
      },
      "DocumentContributor": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/DocumentType"
          },
          "issuingCountry": {
            "type": "string"
          },
          "receiptId": {
            "$ref": "#/components/schemas/ReceiptId"
          },
          "details": {
            "$ref": "#/components/schemas/DocumentDetails"
          }
        },
        "required": [
          "receiptId",
          "details"
        ],
        "additionalProperties": false,
        "description": "Current multi-source records include type and issuingCountry. Legacy single-source receipts may omit either. Details can be empty and contain only requested, supported values."
      },
      "PersonalDetailsDocument": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/DocumentType"
          },
          "issuingCountry": {
            "type": "string"
          },
          "receiptId": {
            "$ref": "#/components/schemas/ReceiptId"
          }
        },
        "required": [
          "receiptId"
        ],
        "additionalProperties": false,
        "description": "Required when a receipt-backed request asked for Personal Details; optional metadata can be absent for legacy single-source records. Receipt/type/country must bind to the corresponding documents[] contributor."
      },
      "LegacyDocument": {
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": [
              "passport",
              "id_card",
              "driving_license",
              "residence_permit"
            ]
          },
          "issuing_country": {
            "type": "string"
          },
          "receipt_id": {
            "$ref": "#/components/schemas/ReceiptId"
          }
        },
        "required": [
          "receipt_id"
        ],
        "additionalProperties": false,
        "deprecated": true,
        "description": "Transitional compatibility object; new consumers use documents[]. Never request legacy field tokens based on this response object."
      },
      "SessionResult": {
        "type": "object",
        "properties": {
          "session_id": {
            "type": "string"
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "description": "Stored terminal last_status, falling back to status. Not a new assurance claim."
          },
          "result": {
            "$ref": "#/components/schemas/PersonalDetails"
          },
          "document": {
            "$ref": "#/components/schemas/LegacyDocument"
          },
          "documents": {
            "type": "array",
            "minItems": 1,
            "maxItems": 8,
            "items": {
              "$ref": "#/components/schemas/DocumentContributor"
            }
          },
          "personalDetailsDocument": {
            "$ref": "#/components/schemas/PersonalDetailsDocument"
          }
        },
        "required": [
          "session_id",
          "status",
          "result"
        ],
        "additionalProperties": false,
        "description": "Private consuming response. No provenance structures are returned for receipt-less legacy/ineligible scope. Receipt-backed document-only requests omit personalDetailsDocument; requested Personal Details add it. Current multi-source records have canonical type/country. No standalone assurance object.",
        "dependentRequired": {
          "personalDetailsDocument": [
            "documents"
          ],
          "documents": [
            "document"
          ]
        }
      },
      "ReceiptDocument": {
        "type": "object",
        "properties": {
          "type": {
            "$ref": "#/components/schemas/DocumentType"
          },
          "issuingCountry": {
            "type": "string",
            "pattern": "^[A-Z]{3}$"
          }
        },
        "required": [
          "type",
          "issuingCountry"
        ],
        "additionalProperties": false
      },
      "VerificationClient": {
        "type": "object",
        "properties": {
          "platform": {
            "type": "string",
            "enum": [
              "ios",
              "android"
            ]
          },
          "surface": {
            "type": "string",
            "enum": [
              "full_app",
              "app_clip",
              "android_app"
            ]
          },
          "build": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991
          }
        },
        "required": [
          "platform",
          "surface",
          "build"
        ],
        "additionalProperties": false
      },
      "DocumentReceipt": {
        "type": "object",
        "properties": {
          "receiptId": {
            "$ref": "#/components/schemas/ReceiptId"
          },
          "receiptVersion": {
            "const": 1
          },
          "issuedAt": {
            "type": "string",
            "format": "date-time"
          },
          "receipt": {
            "type": "string",
            "description": "Original compact signed JWS; opaque to this envelope. Verify alg/typ/kid/issuer/audience with trusted configuration; decoding is not verification."
          },
          "document": {
            "$ref": "#/components/schemas/ReceiptDocument"
          },
          "verified_with": {
            "$ref": "#/components/schemas/VerificationClient"
          },
          "receipt_id": {
            "$ref": "#/components/schemas/ReceiptId"
          },
          "receipt_version": {
            "const": 1
          },
          "issued_at": {
            "type": "string",
            "format": "date-time"
          }
        },
        "required": [
          "receiptId",
          "receiptVersion",
          "issuedAt",
          "receipt",
          "receipt_id",
          "receipt_version",
          "issued_at"
        ],
        "additionalProperties": false,
        "description": "Persistent, non-consuming historical evidence. document/verified_with are independently optional provenance outside signed claims. Transitional aliases equal canonical values. Lifecycle availability does not promise permanent retention."
      },
      "PublicJwk": {
        "type": "object",
        "properties": {
          "kty": {
            "const": "RSA"
          },
          "kid": {
            "type": "string"
          },
          "use": {
            "const": "sig"
          },
          "alg": {
            "const": "RS256"
          },
          "n": {
            "type": "string"
          },
          "e": {
            "type": "string"
          },
          "key_ops": {
            "type": "array",
            "items": {
              "const": "verify"
            }
          },
          "verihop_purpose": {
            "type": "string"
          }
        },
        "required": [
          "kty",
          "kid",
          "use",
          "alg",
          "n",
          "e"
        ],
        "additionalProperties": false
      },
      "Jwks": {
        "type": "object",
        "properties": {
          "keys": {
            "type": "array",
            "minItems": 1,
            "items": {
              "$ref": "#/components/schemas/PublicJwk"
            }
          }
        },
        "required": [
          "keys"
        ],
        "additionalProperties": false
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "field": {
            "type": "string"
          },
          "reason": {
            "type": [
              "string",
              "null"
            ]
          },
          "limit_bytes": {
            "type": "integer"
          },
          "limit": {
            "type": "integer"
          },
          "window": {
            "type": "string",
            "enum": [
              "minute",
              "day"
            ]
          },
          "retry_after_seconds": {
            "type": "integer",
            "minimum": 1
          },
          "availability": {
            "type": "string",
            "enum": [
              "revoked",
              "held",
              "erased"
            ]
          },
          "trust": {
            "type": "string",
            "enum": [
              "untrusted",
              "restricted",
              "unavailable"
            ]
          }
        },
        "required": [
          "error",
          "request_id"
        ],
        "additionalProperties": false,
        "description": "Application JSON envelope. Ordinary 4xx/503 include message; mapped internal_error may omit it. Error/status/correlation are safe diagnostics; never log request/result bodies or tokens."
      }
    },
    "headers": {
      "XRequestId": {
        "description": "Correlation ID, including application errors.",
        "schema": {
          "type": "string"
        },
        "required": true
      },
      "CacheControlPrivate": {
        "description": "Credentialed responses are not cached.",
        "schema": {
          "const": "no-store"
        },
        "required": true
      },
      "IdempotencyKey": {
        "description": "Echoed when a valid key is associated with the response.",
        "schema": {
          "type": "string"
        },
        "required": false
      },
      "IdempotencyStatus": {
        "description": "Known reservation outcome. Some early conflicts omit it.",
        "schema": {
          "type": "string",
          "enum": [
            "created",
            "replayed",
            "conflict",
            "in_progress",
            "expired"
          ]
        },
        "required": false
      },
      "RetryAfter": {
        "description": "Seconds until the next minute/UTC-day admission window.",
        "schema": {
          "type": "string",
          "pattern": "^[0-9]+$"
        },
        "required": true
      },
      "CacheControlPublic": {
        "description": "Credentialed responses are not cached.",
        "schema": {
          "const": "public, max-age=300"
        },
        "required": true
      }
    },
    "responses": {
      "CreateSession401": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "missing_bearer_token",
                        "invalid_api_key"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "CreateSession403": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "customer_inactive",
                        "api_key_environment_mismatch",
                        "pilot_assurance_not_approved",
                        "pilot_use_case_not_approved"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "CreateSession413": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "request_body_too_large"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "CreateSession500": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "internal_error"
                      ]
                    }
                  },
                  "required": []
                }
              ]
            }
          }
        }
      },
      "CreateSession400": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "invalid_request_body",
                        "request_too_large",
                        "invalid_fields",
                        "too_many_fields",
                        "invalid_field_token",
                        "invalid_allowed_documents",
                        "unsupported_document_detail_combination",
                        "invalid_callback_url",
                        "invalid_app_name",
                        "invalid_header",
                        "invalid_assurance_profile",
                        "invalid_risk_context",
                        "unknown_risk_context_field",
                        "invalid_risk_use_case",
                        "invalid_consequential_decision",
                        "invalid_transaction_value_minor",
                        "invalid_risk_currency",
                        "unexpected_risk_currency",
                        "pilot_risk_context_required",
                        "missing_callback_url",
                        "callback_allowlist_required",
                        "callback_host_not_allowed",
                        "allowed_fields_required",
                        "field_not_allowed",
                        "invalid_idempotency_key",
                        "invalid_request_body_encoding"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "CreateSession409": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          },
          "idempotency-key": {
            "$ref": "#/components/headers/IdempotencyKey"
          },
          "idempotency-status": {
            "$ref": "#/components/headers/IdempotencyStatus"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "higher_assurance_or_manual_review_required",
                        "idempotency_key_conflict",
                        "idempotency_key_in_progress",
                        "idempotency_key_expired",
                        "session_limit_conflict_retry"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "CreateSession410": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "session_expired"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "CreateSession415": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "unsupported_media_type"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "CreateSession429": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "rate_limit_exceeded",
                        "daily_quota_exceeded"
                      ]
                    },
                    "limit": {
                      "type": "integer",
                      "minimum": 1
                    }
                  },
                  "required": [
                    "message",
                    "limit",
                    "window",
                    "retry_after_seconds"
                  ]
                }
              ]
            }
          }
        }
      },
      "CreateSession201": {
        "description": "New Session or exact replay; replay never extends expires_at.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          },
          "idempotency-key": {
            "$ref": "#/components/headers/IdempotencyKey"
          },
          "idempotency-status": {
            "$ref": "#/components/headers/IdempotencyStatus"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SessionCreated"
            }
          }
        }
      },
      "CreateSession200": {
        "description": "Compatibility replay of an older stored 200 success; new creation is 201.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          },
          "idempotency-key": {
            "$ref": "#/components/headers/IdempotencyKey"
          },
          "idempotency-status": {
            "$ref": "#/components/headers/IdempotencyStatus"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SessionCreated"
            }
          }
        }
      },
      "GetSession403": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "customer_inactive",
                        "api_key_environment_mismatch"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "GetSession400": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "invalid_request_body_encoding"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "GetSession404": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "session_not_found"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "GetSession200": {
        "description": "Read-only non-PII snapshot; stored availability is not consumption/deadline authority.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SessionStatus"
            }
          }
        }
      },
      "ConsumeSessionResult401": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "missing_bearer_token",
                        "invalid_api_key",
                        "missing_result_token"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "ConsumeSessionResult403": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "customer_inactive",
                        "api_key_environment_mismatch",
                        "invalid_result_token"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "ConsumeSessionResult400": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "result_token_query_not_allowed",
                        "invalid_request_body_encoding"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "ConsumeSessionResult404": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "session_not_found",
                        "result_not_available"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "ConsumeSessionResult409": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "result_token_used"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "ConsumeSessionResult410": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "result_token_expired"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "ConsumeSessionResult503": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "document_receipt_unavailable"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "ConsumeSessionResult200": {
        "description": "Consumes one result token atomically. A lost successful exchange is uncertain; never automatically retry or replace the Session.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/SessionResult"
            }
          }
        }
      },
      "GetDocumentReceipt400": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "invalid_document_receipt_id",
                        "invalid_request_body_encoding"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "GetDocumentReceipt404": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "document_receipt_not_found"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "GetDocumentReceipt409": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "document_receipt_revoked"
                      ]
                    },
                    "availability": {
                      "const": "revoked"
                    },
                    "trust": {
                      "const": "untrusted"
                    }
                  },
                  "required": [
                    "message",
                    "availability",
                    "trust"
                  ]
                }
              ]
            }
          }
        }
      },
      "GetDocumentReceipt410": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "document_receipt_erased"
                      ]
                    },
                    "availability": {
                      "const": "erased"
                    },
                    "trust": {
                      "const": "unavailable"
                    }
                  },
                  "required": [
                    "message",
                    "availability",
                    "trust"
                  ]
                }
              ]
            }
          }
        }
      },
      "GetDocumentReceipt423": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "document_receipt_held"
                      ]
                    },
                    "availability": {
                      "const": "held"
                    },
                    "trust": {
                      "const": "restricted"
                    }
                  },
                  "required": [
                    "message",
                    "availability",
                    "trust"
                  ]
                }
              ]
            }
          }
        }
      },
      "GetDocumentReceipt503": {
        "description": "Application error. Read error and request_id; no result or signed receipt contents.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/Error"
                },
                {
                  "type": "object",
                  "properties": {
                    "error": {
                      "enum": [
                        "document_receipt_verification_unavailable",
                        "document_receipt_unavailable"
                      ]
                    }
                  },
                  "required": [
                    "message"
                  ]
                }
              ]
            }
          }
        }
      },
      "GetDocumentReceipt200": {
        "description": "Owning eligible account, independent of old Session environment/deadline; persistent non-consuming read.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPrivate"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/DocumentReceipt"
            }
          }
        }
      },
      "GetJwks200": {
        "description": "Public keys. Absent optional receipt signer is allowed; a configured loader failure can fail the whole discovery request.",
        "headers": {
          "x-request-id": {
            "$ref": "#/components/headers/XRequestId"
          },
          "Cache-Control": {
            "$ref": "#/components/headers/CacheControlPublic"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Jwks"
            }
          }
        }
      }
    }
  },
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema"
}