SESSIONS

Exchange a same-device response code for its result

POST/v1/sessions/{sessionId}/response

One-time result exchange for the configured redirect_uri callback. The Origin must match the callback and SHA-256 of browser_session_verifier must match the browser_session_challenge supplied at session creation. Successful same-device sessions remain VERIFYING until this exchange; only then are VERIFIED events, audit, usage, and webhook delivery emitted. Send both proofs in the JSON body, never in a URL. Claims and proofs are cleared after exchange or the 30-second result deadline.

Backend integrationNo tenant API key is required for this public protocol operation.

Try itAvailable for creating, reading, and deleting verification sessions in Test. Other operations are reference-only; API-key protected routes require a tenant API key on your backend. Open a session request

Parameters

Parameters for POST /v1/sessions/{sessionId}/response
Name	Location	Required	Schema	Description
`sessionId`	path	Yes	`string`	Session ID

Request bodyRequired

Request fields

Required fields only

browser_session_verifierstringrequired
response_codestringrequired

View JSON schema

{
  "type": "object",
  "required": [
    "response_code",
    "browser_session_verifier"
  ],
  "properties": {
    "browser_session_verifier": {
      "type": "string",
      "minLength": 43,
      "maxLength": 43,
      "pattern": "^[A-Za-z0-9_-]{43}$"
    },
    "response_code": {
      "type": "string",
      "minLength": 22,
      "maxLength": 22,
      "pattern": "^[A-Za-z0-9_-]{22}$"
    }
  },
  "additionalProperties": false
}

Raw JSON schema

{
  "type": "object",
  "required": [
    "response_code",
    "browser_session_verifier"
  ],
  "properties": {
    "browser_session_verifier": {
      "type": "string",
      "minLength": 43,
      "maxLength": 43,
      "pattern": "^[A-Za-z0-9_-]{43}$"
    },
    "response_code": {
      "type": "string",
      "minLength": 22,
      "maxLength": 22,
      "pattern": "^[A-Za-z0-9_-]{22}$"
    }
  },
  "additionalProperties": false
}

Responses

Response 200

JSON response

application/json · Response schema

session_idstringrequired
statusstringrequired: Allowed valuesCREATEDPENDINGVERIFYINGVERIFIEDFAILEDEXPIRED
livemodebooleanrequired: Whether this session targets live data. False means sandbox/test data.
expires_atstring · date-timeoptional
claimsobjectoptional
reasonstringoptional
failure_categorystringoptional: PII-free allow-listed verifier failure category, present only for failed sessions when classified.
Allowed valuesREQUEST_SETUP_REJECTEDWALLET_REJECTED_PRESENTATIONREQUEST_BINDING_INVALIDPRESENTATION_MALFORMEDREQUIRED_DISCLOSURE_MISSINGCREDENTIAL_CLAIM_INVALIDISSUER_TRUST_INVALIDCREDENTIAL_SIGNATURE_INVALIDCREDENTIAL_VALIDITY_INVALIDCREDENTIAL_REVOKEDSIGNING_CERTIFICATE_REVOKEDREVOCATION_STATUS_UNAVAILABLEMDOC_ISSUER_AUTH_INVALIDMDOC_DEVICE_AUTH_INVALIDZKP_VERIFIER_UNAVAILABLESCA_POLICY_NOT_METSCA_AUTHENTICATION_CODE_REUSEDVERIFICATION_UNCLASSIFIED
verification_detailsobjectoptional

View JSON schema

{
  "type": "object",
  "required": [
    "session_id",
    "status",
    "livemode"
  ],
  "properties": {
    "session_id": {
      "type": "string"
    },
    "status": {
      "type": "string",
      "enum": [
        "CREATED",
        "PENDING",
        "VERIFYING",
        "VERIFIED",
        "FAILED",
        "EXPIRED"
      ]
    },
    "livemode": {
      "type": "boolean",
      "description": "Whether this session targets live data. False means sandbox/test data."
    },
    "expires_at": {
      "type": "string",
      "format": "date-time"
    },
    "claims": {
      "type": "object"
    },
    "reason": {
      "type": "string"
    },
    "failure_category": {
      "type": "string",
      "enum": [
        "REQUEST_SETUP_REJECTED",
        "WALLET_REJECTED_PRESENTATION",
        "REQUEST_BINDING_INVALID",
        "PRESENTATION_MALFORMED",
        "REQUIRED_DISCLOSURE_MISSING",
        "CREDENTIAL_CLAIM_INVALID",
        "ISSUER_TRUST_INVALID",
        "CREDENTIAL_SIGNATURE_INVALID",
        "CREDENTIAL_VALIDITY_INVALID",
        "CREDENTIAL_REVOKED",
        "SIGNING_CERTIFICATE_REVOKED",
        "REVOCATION_STATUS_UNAVAILABLE",
        "MDOC_ISSUER_AUTH_INVALID",
        "MDOC_DEVICE_AUTH_INVALID",
        "ZKP_VERIFIER_UNAVAILABLE",
        "SCA_POLICY_NOT_MET",
        "SCA_AUTHENTICATION_CODE_REUSED",
        "VERIFICATION_UNCLASSIFIED"
      ],
      "description": "PII-free allow-listed verifier failure category, present only for failed sessions when classified."
    },
    "verification_details": {
      "type": "object"
    }
  }
}

Response 400

Invalid session ID

application/json · Response schema

errorstringrequired
messagestringrequired

View JSON schema

{
  "type": "object",
  "required": [
    "error",
    "message"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}

Response 404

Response code is invalid, expired, or already used

application/json · Response schema

errorstringrequired
messagestringrequired

View JSON schema

{
  "type": "object",
  "required": [
    "error",
    "message"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}

Response 429

Rate limit exceeded

application/json · Response schema

errorstringrequired
messagestringrequired

View JSON schema

{
  "type": "object",
  "required": [
    "error",
    "message"
  ],
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  }
}

← All public operations