Revalidate verification

POST 
/v2/config/digital-wallet/openid/sdjwt/verification/history/:presentationExchangeId/revalidate

Revalidates a verification exchange that the holder already answered.

The digital wallet checks the credential signatures, the revocation status and the trust chain again. The server then writes the new presentationValidity and verified values to the record and returns the full record. The other properties of the record do not change.

The request has no body. The server discards a body if you send one.

The path of this operation is /v2, but the response holds the V3 verification exchange record: vpTokenResponse is an array, presentation is an array, and the V3-only properties are present. This is the only V2 verification operation that answers with the V3 shape.

The server does not compute requestExpired on this operation. Read the record with GET /v3/config/digital-wallet/openid/sdjwt/verification/history/{presentationExchangeId} to get a current value.

Request

Path Parameters

presentationExchangeId stringrequired
Unique identifier of the verification exchange record. This is the presentationExchangeId property of the record, not its id property.
Example: 8e9c0a94-3b7d-4f2c-9d11-2f5a0b1c8d3e

Header Parameters

X-SandboxOrgId stringrequired
Optional. Unique identifier of the sandbox organisation to use for this request. When you send this header, the service runs the operation in the context of the named sandbox organisation, that is, against the wallet of that sandbox organisation and not against the main wallet of the organisation. Leave the header out to use the main wallet.
The service reads this header only when you authenticate with a bearer access token. When you authenticate with an API key, the service takes the sandbox organisation from the API key and ignores this header. To run an API-key call in a sandbox organisation, bind the key to the sandbox organisation with PUT /v2/config/admin/apikey/{apiKeyId}/sandbox-org instead.
X-SubwalletId is the deprecated name of this header. The service continues to accept it, but X-SandboxOrgId wins if you send both headers.
The sandbox organisation must exist, must belong to your organisation and must be deployed. An unknown identifier, an identifier of a sandbox organisation that is not deployed, and an identifier that belongs to a different organisation all make the call fail with HTTP 400.
Example: 6889e1a4c5b2f30001a3d710

Responses

200

The digital wallet revalidated the presentation. The response holds the record with the new presentationValidity and verified values.

Response Headers

application/json

Schema

Schema

verificationHistory objectrequired
Verification exchange record. The record tracks one OpenID for Verifiable Presentation (OpenID4VP) verification, from the Authorization Request to the verification result.
The server returns every property of this schema on every operation, except dcApiRequest and dcApiProtocol. A property that has no value yet holds the empty value for its type: "" for a string, 0 for a number, false for a boolean and null for an object or an array.
presentationExchangeId stringrequired
Unique identifier of the verification exchange. Give this value as the presentationExchangeId path parameter to read, delete or revalidate the record, and to receive a DC API response for it.
id stringrequired
Internal record identifier that the server makes when it stores the record. No operation accepts this value. Use presentationExchangeId to address the record.
vpTokenQrCode stringrequired
OpenID4VP Authorization Request URI encoded for QR code display or deep link. The holder's wallet scans or clicks this to initiate the presentation flow. Empty when using DC API response modes (dc_api or dc_api.jwt).
vpTokenRequestState stringrequired
State parameter for the OpenID4VP Authorization Request, used to correlate the request with the response.
vpTokenRequest stringrequired
Full OpenID4VP Authorization Request URI or payload. Empty when using DC API response modes (dc_api or dc_api.jwt).
presentationSubmission object
Wrapper that holds the Presentation Submission object of the wallet.
DCQL is the only supported query form, and a DCQL Authorization Response carries no Presentation Submission, so the server returns null here for every verification that a current presentation definition starts. A value is present only on an old record that a DIF Presentation Exchange definition made. Read presentation to get the credentials of the holder.
presentation_submission object
DIF Presentation Exchange Submission object that maps the credentials of the holder to the requirements of the verifier. Kept for old records only.
definition_id stringrequired
Identifier of the Presentation Definition that this submission fulfills.
descriptor_map object[]required
Array of Descriptor Map entries mapping each requested credential to its location in the Verifiable Presentation.
Array [
format stringrequired
Credential format of the matched credential (e.g. jwt_vc_json, dc+sd-jwt, mso_mdoc).
id stringrequired
Identifier of the Input Descriptor from the Presentation Definition that this entry satisfies.
path stringrequired
JSONPath expression pointing to the Verifiable Credential within the Verifiable Presentation token.
path_nested object
Nested path descriptor for credentials wrapped in envelope formats (e.g. JWT inside a VP JWT).
format stringrequired
Credential format of the nested credential (e.g. jwt_vc_json, dc+sd-jwt, mso_mdoc).
id stringrequired
Identifier of the Input Descriptor from the Presentation Definition that this nested entry satisfies.
path stringrequired
JSONPath expression pointing to the credential within the nested envelope.
]
id stringrequired
Unique identifier for this Presentation Submission.
status stringrequired
Possible values: [request_sent, request_received, presentation_pending, presentation_acked]
Lifecycle status of the verification exchange:
1. request_sent: The server made the OpenID4VP Authorization Request. The exchange waits for the holder.
2. request_received: The wallet of the holder got, or scanned, the Authorization Request.
3. presentation_pending: The wallet started the response but the verifier did not get a complete Authorization Response yet.
4. presentation_acked: The holder sent the Verifiable Presentation and the verifier processed it.
verified booleanrequired
Result of the verification of the Verifiable Presentation. The server checks the cryptographic signatures, the credential status and the presented claims against the DCQL query of the presentation definition.
createdAt numberrequired
Unix timestamp (in seconds) when this verification record was created.
updatedAt numberrequired
Unix timestamp (in seconds) when this verification record was last modified.
presentationDefinitionId stringrequired
Identifier of the presentation definition used for this verification request.
openIdOrganisationId stringrequired
Identifier of the OpenID4VP organisation that initiated this verification request.
holder objectrequired
Contains the metadata describing a holder. For e.g. Name, location, logo e.t.c
name stringrequired
Identifier of the holder. For .e.g. DID or Name obtained from client metadata if available.
presentation object[]
Decoded credentials that the holder presented. The shape of each entry follows the credential format. null until the holder answers.
vpTokenResponse string[]
Verifiable Presentation tokens that the wallet sent. The array holds one entry for each credential that the Authorization Request asked for. null until the wallet answers.
transactionData object
Transaction data confirmed by the holder during the presentation flow.
property name* any
Transaction data confirmed by the holder during the presentation flow.
transactionDataBase64 stringrequired
Base64url encoding of the transaction data that the Authorization Request holds.
credentialExchangeId stringrequired
Identifier of the credential issuance exchange that this verification started, if the flow issues a credential after the verification. Always empty on the response of the send operation. The server fills it in later, when the issuance flow starts.
responseType stringrequired
Possible values: [vp_token, id_token, device_response]
OAuth 2.0 response type of the Authorization Request.
idToken stringrequired
OpenID Connect ID Token from the holder. Present only when responseType is id_token.
idTokenDecoded object
Decoded payload of the ID Token of the holder.
property name* any
Decoded payload of the ID Token of the holder.
dataAgreementId stringrequired
Identifier of the data agreement record that this verification exchange created.
userId stringrequired
Identifier of the dashboard user or individual that started this verification request.
requestExpired booleanrequired
true when the exp claim of vpTokenRequest is in the past. The wallet cannot use an expired Authorization Request. The read and list operations compute this value when they answer. The send and revalidate operations always return false.
requestExpiryTime numberrequired
Unix timestamp in seconds when the Authorization Request expires. The server reads this value from the exp claim of vpTokenRequest. 0 when the request has no expiry.
presentationValidity object[]
Validation result for each credential in the presentation, with the signature check, the expiry check and the revocation status. The revalidate operation writes a new value here. null until the holder answers.
clientIdScheme stringrequired
Possible values: [redirect_uri, did, verifier_attestation, x509_san_dns, x509_hash]
Client ID scheme used by the verifier in the OpenID4VP Authorization Request.
directPostRedirectUri stringrequired
URI the wallet redirects to after posting the Authorization Response. Empty when using DC API response modes (dc_api or dc_api.jwt).
responseMode stringrequired
Possible values: [direct_post, direct_post.jwt, dc_api, dc_api.jwt, iar-post, iar-post.jwt]
OpenID4VP response mode determining how the Authorization Response is delivered:
• direct_post: Response sent via HTTP POST to the verifier's redirect_uri without encryption.
• direct_post.jwt: Response sent via HTTP POST encrypted as a JWE.
• dc_api: Response delivered over the W3C Digital Credentials API transport without JWE encryption. Compatible with both signed and unsigned dcApiRequestType values.
• dc_api.jwt: Response delivered over the W3C Digital Credentials API transport encrypted as a JWE.
• iar-post: Response sent through the Interactive Authorisation Request transport without encryption.
• iar-post.jwt: Response sent through the Interactive Authorisation Request transport encrypted as a JWE.
verifierAttestation stringrequired
Verifier Attestation JWT sent to the holder, proving the verifier's authorization.
individualId stringrequired
Identifier of the individual that the server sent the Authorization Request to with a push notification. Empty when the send request did not set individualId.
mapperId stringrequired
External identifier of the individual that the server sent the Authorization Request to with a push notification. Empty when the send request did not set mapperId.
dataAgreement object
Data agreement that gives the terms for this verification exchange.
property name* any
Data agreement that gives the terms for this verification exchange.
nonce stringrequired
Cryptographic nonce used in the OpenID4VP Authorization Request to ensure freshness and prevent replay attacks.
dcApiProtocol string
Possible values: [openid4vp-v1-unsigned, openid4vp-v1-signed, org-iso-mdoc]
Digital Credentials API exchange protocol identifier returned when the presentation definition is configured for DC API response modes. Identifies the protocol variant used with the W3C Digital Credentials API (navigator.credentials.get()):
• openid4vp-v1-unsigned: The Authorization Request is passed unencrypted to the browser's DC API. The browser can inspect the request for risk analysis. Use for development/testing only.
• openid4vp-v1-signed: The Authorization Request is signed by the verifier's key and passed as an opaque string to the browser's DC API. Provides verifier authentication. Recommended for production.
• org-iso-mdoc: The Authorization Request follows ISO 18013-7 Annex C. The wallet answers with an encrypted CBOR EncryptedResponse. Only present when responseMode is dc_api or dc_api.jwt.
dcApiRequest object
Request object for the W3C Digital Credentials API, structured for browser invocation via navigator.credentials.get(). Contains browser-specific request formats for Chrome and Safari. Only present when responseMode is dc_api or dc_api.jwt.
chrome object
Digital Credentials API request format for Chromium-based browsers. Uses the providers structure per the W3C Digital Credentials API specification.
digital object
Digital credential request options for Chromium-based browsers.
providers object[]
Array of credential request providers, each specifying a protocol and request data.
Array [
protocol string
Digital Credentials API exchange protocol identifier (e.g. openid4vp-v1-signed, openid4vp-v1-unsigned).
request object
The OpenID4VP Authorization Request payload. Structure varies by protocol:
• For openid4vp-v1-signed: Contains { "request": "<signed-JWT>" }, a JWT signed by the verifier's key.
• For openid4vp-v1-unsigned: Contains the full Authorization Request object with client_metadata, dcql_query, nonce, response_mode, response_type.
property name* any
The OpenID4VP Authorization Request payload. Structure varies by protocol:
• For openid4vp-v1-signed: Contains { "request": "<signed-JWT>" }, a JWT signed by the verifier's key.
• For openid4vp-v1-unsigned: Contains the full Authorization Request object with client_metadata, dcql_query, nonce, response_mode, response_type.
]
safari object
Digital Credentials API request format for Safari-based browsers. Uses the requests structure.
digital object
Digital credential request options for Safari-based browsers.
requests object[]
Array of credential requests for Safari, each containing data and protocol.
Array [
data string
JSON-stringified Authorization Request payload (Safari's DC API expects a string, not an object).
Decoding it yields the same structure that Chrome receives in request:
• For openid4vp-v1-signed: { "request": "<signed-JWT>" }.
• For openid4vp-v1-unsigned: the full inline Authorization Request object (response_type, response_mode, nonce, dcql_query, client_metadata, …).
protocol string
Digital Credentials API exchange protocol identifier (e.g. openid4vp-v1-signed, openid4vp-v1-unsigned).
]
requiresEncryption booleanrequired
Indicates whether the OpenID4VP Authorization Response must be encrypted as a JWE. true when responseMode is direct_post.jwt or dc_api.jwt. false when responseMode is direct_post or dc_api.
signatureStamp booleanrequired
When false, the signature stamp is hidden in signed PDFs.
signatureCoordinate integer[]
Possible values: >= 4, <= 4
Page coordinates of the signature in the signed PDF, as [x1, y1, x2, y2] in points.
files object[]
List of files generated during the verification, including signed and unsigned PDF documents.
Array [
credentialId string
Identifier of the credential associated with this file.
error stringnullable
Error code if signing failed, null otherwise.
errorDescription stringnullable
Detailed error message if signing failed, null otherwise.
signedFile uri
URL of the signed PDF file.
unsignedFile uri
URL of the unsigned PDF file.
]

Example (from schema)

{
  "verificationHistory": {
    "presentationExchangeId": "8e9c0a94-3b7d-4f2c-9d11-2f5a0b1c8d3e",
    "id": "6821b4b0f5b1c2a3d4e5f6a7",
    "vpTokenQrCode": "string",
    "vpTokenRequestState": "string",
    "vpTokenRequest": "string",
    "presentationSubmission": {
      "presentation_submission": {
        "definition_id": "string",
        "descriptor_map": [
          {
            "format": "string",
            "id": "string",
            "path": "string",
            "path_nested": {
              "format": "string",
              "id": "string",
              "path": "string"
            }
          }
        ],
        "id": "string"
      }
    },
    "status": "request_sent",
    "verified": true,
    "createdAt": 0,
    "updatedAt": 0,
    "presentationDefinitionId": "string",
    "openIdOrganisationId": "string",
    "holder": {
      "name": "string"
    },
    "presentation": [
      {}
    ],
    "vpTokenResponse": [
      "string"
    ],
    "transactionData": {},
    "transactionDataBase64": "string",
    "credentialExchangeId": "string",
    "responseType": "vp_token",
    "idToken": "string",
    "idTokenDecoded": {},
    "dataAgreementId": "string",
    "userId": "string",
    "requestExpired": true,
    "requestExpiryTime": 1747015200,
    "presentationValidity": [
      {}
    ],
    "clientIdScheme": "redirect_uri",
    "directPostRedirectUri": "string",
    "responseMode": "direct_post",
    "verifierAttestation": "string",
    "individualId": "string",
    "mapperId": "string",
    "dataAgreement": {},
    "nonce": "string",
    "dcApiProtocol": "openid4vp-v1-unsigned",
    "dcApiRequest": {
      "chrome": {
        "digital": {
          "providers": [
            {
              "protocol": "string",
              "request": {}
            }
          ]
        }
      },
      "safari": {
        "digital": {
          "requests": [
            {
              "data": "string",
              "protocol": "string"
            }
          ]
        }
      }
    },
    "requiresEncryption": true,
    "signatureStamp": true,
    "signatureCoordinate": [
      100,
      100,
      200,
      150
    ],
    "files": [
      {
        "credentialId": "string",
        "error": "string",
        "errorDescription": "string",
        "signedFile": "string",
        "unsignedFile": "string"
      }
    ]
  }
}

400

The organisation is unknown, the digital wallet deployment is not resolved, no verification exchange record has the supplied presentationExchangeId, or the digital wallet refused the revalidation.

Response Headers

application/json

Schema

Schema

errorCode integerrequired
errorDescription stringrequired

Example (from schema)

{
  "errorCode": 400,
  "errorDescription": "Bad input parameter"
}

401

Unauthorized

Response Headers

application/json

Schema

Schema

errorCode integerrequired
errorDescription stringrequired

Example (from schema)

{
  "errorCode": 400,
  "errorDescription": "Bad input parameter"
}

500

Internal server error

Response Headers

application/json

Schema

Schema

errorCode integerrequired
errorDescription stringrequired

Example (from schema)

{
  "errorCode": 400,
  "errorDescription": "Bad input parameter"
}

Loading...