Skip to main content

Send verification request

POST 
/v3/config/digital-wallet/openid/sdjwt/verification/send

Sends an OpenID4VP Authorization Request from a stored presentation definition. Set presentationDefinitionId: the server reads the DCQL query, the response mode, the transaction data template and the DC API settings from that record.

The response mode of the presentation definition sets the transport:

  • direct_post / direct_post.jwt: the response holds vpTokenQrCode and vpTokenRequest. Show vpTokenQrCode as a QR code, or open it as a deep link. The wallet posts the response to the response URI of the verifier.
  • dc_api / dc_api.jwt: the response holds dcApiRequest (one shape for Chrome and one for Safari) and dcApiProtocol. The verifier frontend gives dcApiRequest.chrome (or dcApiRequest.safari) to navigator.credentials.get() and forwards the answer of the wallet to POST /v2/config/digital-wallet/openid/sdjwt/verification/history/{presentationExchangeId}/receive. vpTokenQrCode and vpTokenRequest are empty.

Send transactionData when, and only when, the presentation definition sets a transactionDataDefinitionType.

Set individualId or mapperId to push the Authorization Request to the device of a known individual. The individual must have a push notification token. Do not set both properties in one request.

Read presentationExchangeId from the response. Every other verification operation takes that value as its path parameter. id holds the same value.

The request lifetime is presentationRequestExpiresIn of the verifier global configuration, counted from createdAt.

Request​

Body

required

Delivery options for the Authorization Request. Set presentationDefinitionId to name the stored presentation definition that holds the credential requirements.

    presentationDefinitionId stringrequired

    Identifier of a stored presentation definition. The server reads the DCQL query, the response mode, the transaction data template and the DC API settings from this record. A value shorter than three characters, or an unknown identifier, gives HTTP 400.

    requestByReference boolean

    Default value: false

    When true, the server passes the Authorization Request by reference with the request_uri parameter. The wallet then gets the full request from that URI. Use this option for large Authorization Requests.

    transactionData object

    Transaction data to add to the Authorization Request. The holder must approve this data before the wallet sends the presentation.

    Give this property when, and only when, the presentation definition that presentationDefinitionId names sets a transaction data template type. The server answers with HTTP 400 when the definition sets a template type and the body has no transactionData, and also when the definition sets no template type and the body has transactionData.

    The structure must agree with the JSON Schema of the template type of the presentation definition.

    property name* any

    Transaction data to add to the Authorization Request. The holder must approve this data before the wallet sends the presentation.

    Give this property when, and only when, the presentation definition that presentationDefinitionId names sets a transaction data template type. The server answers with HTTP 400 when the definition sets a template type and the body has no transactionData, and also when the definition sets no template type and the body has transactionData.

    The structure must agree with the JSON Schema of the template type of the presentation definition.

    nonce string

    Cryptographic nonce for the Authorization Request. The server makes a nonce if you do not supply one.

    urlPrefix string

    URL scheme prefix for the Authorization Request deep link that the server returns in vpTokenQrCode. The default is openid4vp://. Use a different prefix to open a specific wallet.

    individualId string

    Identifier of an individual in the organisation. The server sends a push notification with the Authorization Request to the device of this individual. The individual must have a push notification token. Do not set individualId and mapperId together.

    mapperId string

    External identifier that maps to an individual in the organisation. The server sends a push notification with the Authorization Request to the device of that individual. The individual must have a push notification token. Do not set individualId and mapperId together.

    signatureStamp boolean

    Default value: false

    When true, the server puts a visible signature stamp in the signed PDF that the flow makes.

    signatureCoordinate integer[]

    Possible values: >= 4, <= 4

    Page coordinates of the signature in the signed PDF, as [x1, y1, x2, y2] in points. The array must hold exactly four integers.

    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.

Responses​

The server made the Authorization Request and saved the verification exchange record.

Response Headers
    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, dcApiProtocol, cryptographicKeyFormat, cryptographicKeyIdentifier and presentationDefinitionSnapshot, which it leaves out when they hold no value. 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.

      The record has no expiry flag. The request lifetime is presentationRequestExpiresIn of the verifier global configuration, counted from createdAt.

      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

      Identifier of the record. It holds the same value as presentationExchangeId.

      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 objectrequired

      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 digital wallet of the organisation that sent this verification request.

      holder objectrequired

      Metadata of the holder.

      name stringrequired

      Identifier of the holder, for example a DID or the name from the client metadata. An empty string when the server has no value.

      presentation object[]required

      Decoded credentials that the holder presented. The shape of each entry follows the credential format. null until the holder answers.

      vpTokenResponse string[]required

      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 objectrequired

      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, device_response]

      OAuth 2.0 response type of the Authorization Request.

      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.

      presentationValidity object[]required

      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 that the wallet opens after it posts the Authorization Response. Empty for the 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 objectrequired

      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 goes to the DC API of the browser without a signature. The browser can inspect the request for risk analysis. Use it for development and tests only.
      • openid4vp-v1-signed: The verifier key signs the Authorization Request, and the request goes to the DC API of the browser as an opaque string. This gives verifier authentication. Use it for live use.
      • org-iso-mdoc: The Authorization Request follows ISO 18013-7 Annex C. The wallet answers with an encrypted CBOR EncryptedResponse. Only present for the DC API response modes and for iso18013_7_annex_c.
      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

      true when the wallet must encrypt the Authorization Response as a JWE: for the direct_post.jwt and dc_api.jwt response modes, and for iso18013_7_annex_c. false for direct_post and dc_api.

      signatureStamp booleanrequired

      When false, the signature stamp is hidden in signed PDFs.

      signatureCoordinate integer[]required

      Possible values: >= 4, <= 4

      Page coordinates of the signature in the signed PDF, as [x1, y1, x2, y2] in points.

      files object[]required

      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.

    • ]
      • cryptographicKeyIdentifier string

      Key identifier of the key that signed the Authorization Request. The server leaves this property out when the request is not signed.

      cryptographicKeyFormat string

      Possible values: [did:key, x509]

      Format of the key that signed the Authorization Request. The server leaves this property out when the request is not signed.

      presentationDefinitionSnapshot object

      Copy of the presentation definition at the time of the request, in the shape of the presentation definition record. A later change of the presentation definition does not change a request that is already out.

      property name* any

      Copy of the presentation definition at the time of the request, in the shape of the presentation definition record. A later change of the presentation definition does not change a request that is already out.

    Loading...
    Last updated on