Skip to main content

Receive verification

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

Processes an OpenID4VP Authorization Request (V3) received from a verifier. The wallet resolves the verifier's requirements and identifies matching credentials. The V3 record adds DCQL, transaction data, trust list and response encryption fields.

Read presentationId from the response. The filter, read and send operations take that value as their path parameter.

Read status from the response before you go on. When autoPresent is true the wallet can select the credentials and answer the verifier inside this one call, and the status is then presentation_acked. When the wallet finds no credential for the request, it still answers with HTTP 200 and leaves the status at presentation_pending.

When you call this operation again for an Authorization Request that the wallet already answered, the wallet returns the stored record without a change and without an error.

Request​

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

Body

required

Authorization Request that the holder scanned or received, and the key material that the wallet uses for the response.

    vpTokenQrCode stringrequired

    OpenID4VP Authorization Request URI that the holder scanned from the verifier's QR code or received through a deep link. The wallet resolves this URI to get the full Authorization Request.

    autoPresent boolean

    Default value: false

    When true, the wallet selects the matching credentials and sends the Verifiable Presentation without holder interaction. The wallet skips this step when the Authorization Request asks for an ID Token. Default is false.

    kid string

    Key identifier of the wallet key that signs the Verifiable Presentation. If you do not give a value, the wallet uses the default key for the trust anchor.

    trustAnchor string

    Possible values: [did:key, x509]

    Default value: did:key

    Trust anchor that identifies the holder to the verifier. The value sets the key type or DID method that the wallet uses to sign the Verifiable Presentation. Default is did:key.

Responses​

The wallet received and resolved the Authorization Request.

Response Headers
    Schema
      presentation object

      Presentation record in the wallet of the holder. The record tracks one OpenID for Verifiable Presentation (OpenID4VP) Authorization Request that the holder got, and the presentation that the holder sent back.

      This V3 shape keeps vpToken as an array, so the wallet can send more than one Verifiable Presentation in a single Authorization Response.

      The wallet returns every property of this schema on every V3 holder operation. 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.

      id stringrequired

      Internal record identifier of the presentation.

      presentationId stringrequired

      Unique identifier of this presentation in the wallet of the holder. Use this identifier to read the record, to send the presentation, or to delete the record.

      presentationExchangeId stringrequired

      Identifier of the verification exchange at the verifier. It links this presentation to the verification history record of the verifier.

      openIdOrganisationId stringrequired

      Identifier of the digital wallet deployment that holds this presentation record.

      organisationId stringrequired

      Identifier of the organisation that owns the wallet of the holder.

      presentationSubmission object

      Presentation Submission object of the DIF Presentation Exchange specification. It maps the credentials of the holder to the requirements of the verifier.

      DCQL is the only query form that an iGrant.io verifier sends, and a DCQL Authorization Response carries no Presentation Submission, so the wallet returns null here for such a request. A value is present only when an outside verifier still sends a DIF Presentation Exchange definition.

      definition_id stringrequired

      Identifier of the presentation definition that this submission fulfils.

      descriptor_map object[]required

      Descriptor Map entries. Each entry gives the position of one requested credential in the Verifiable Presentation.

    • Array [
      • format stringrequired

      Credential format of the matched credential, for example jwt_vc_json, dc+sd-jwt or mso_mdoc.

      id stringrequired

      Identifier of the Input Descriptor that this entry satisfies.

      path stringrequired

      JSONPath expression that points to the credential in the Verifiable Presentation token.

      path_nested object

      Nested path descriptor for credentials in an envelope format, for example a JWT in a VP JWT.

      format stringrequired

      Credential format of the nested credential, for example jwt_vc_json, dc+sd-jwt or mso_mdoc.

      id stringrequired

      Identifier of the Input Descriptor that this nested entry satisfies.

      path stringrequired

      JSONPath expression that points to the credential in the envelope.

    • ]
      • id stringrequired

      Unique identifier of this Presentation Submission.

      vpToken string[]

      Verifiable Presentation tokens that the wallet sent to the verifier. The array holds one entry for each credential that the Authorization Request asked for. The array is empty until the holder sends the presentation.

      status stringrequired

      Possible values: [presentation_pending, presentation_acked]

      Lifecycle status of the presentation in the wallet of the holder:

      1. presentation_pending: The holder must select the matching credentials and send the Verifiable Presentation to the verifier.
      2. presentation_acked: The wallet sent the Verifiable Presentation and the verifier accepted it.
      verified booleanrequired

      true when the verifier accepted the presentation and the checks of the verifier passed. The receive and send operations always return false. The server sets this value later, when the verification webhook reports the result.

      presentationValidity object[]

      Validation result for each credential in the presentation. Each entry holds the result of the signature check, the expiry check and the revocation check. The receive and send operations always return null. The server sets this value later, when the verification webhook reports the result.

      vpRequestState stringrequired

      State value of the Authorization Request of the verifier. The wallet returns this value with the Authorization Response so that the verifier can match the two.

      clientId stringrequired

      Client identifier of the verifier from the Authorization Request, for example a URI or a DID.

      redirectUri stringrequired

      Redirect URI from the Authorization Request. The wallet posts the Authorization Response to this URI.

      requestUri stringrequired

      Request URI of the Authorization Request. The wallet gets the full Authorization Request from this URI when the verifier passes the request by reference.

      responseRedirectUri stringrequired

      Redirect URI that the verifier returned in the Authorization Response. The wallet sends the holder to this URI after the verifier processed the presentation.

      presentationDefinition stringrequired

      DIF Presentation Exchange definition of the verifier, as a serialised JSON string. Empty when the verifier sent a DCQL query, which is the only query form that an iGrant.io verifier sends. Read dcqlQuery for the credential and claim requirements.

      nonce stringrequired

      Cryptographic nonce from the Authorization Request. The wallet puts this value in the Key Binding JWT to keep the presentation fresh and to stop replay.

      responseType stringrequired

      Possible values: [vp_token, id_token, device_response]

      OAuth 2.0 response type of the Authorization Request. It tells the wallet what to send back.

      credentialId stringrequired

      Identifier of the credential in the wallet that the holder chose for this presentation.

      clientMetadata objectrequired

      Metadata of the verifier from the Authorization Request. The wallet shows this information to the holder before the holder approves the presentation.

      clientName stringrequired

      Display name of the verifier.

      logoUri stringrequired

      URL of the logo of the verifier.

      location stringrequired

      Location or address of the verifier.

      coverUri stringrequired

      URL of the cover image of the verifier.

      description stringrequired

      Description of the verifier.

      presentation object[]

      Credentials that the Verifiable Presentation holds. The array is empty until the holder sends the presentation.

    • Array [
      • id stringrequired

      Identifier of the DCQL credential query that this credential satisfies. For a request from an outside verifier that still uses Presentation Exchange, this is the Input Descriptor identifier.

      credentialId stringrequired

      Identifier of the credential in the wallet of the holder.

      type string[]

      Credential types of the presented W3C Verifiable Credential. The wallet leaves this property out for other credential formats.

      credentialSubject object

      Disclosed claims of a presented W3C VC JWT credential. The wallet leaves this property out for other credential formats.

      property name* any

      Disclosed claims of a presented W3C VC JWT credential. The wallet leaves this property out for other credential formats.

      vct string

      Verifiable Credential Type of a presented IETF SD-JWT VC credential. The wallet leaves this property out for other credential formats.

      doctype string

      Document type of a presented ISO 18013-5 mDoc credential. The wallet leaves this property out for other credential formats.

      claims object

      Disclosed claims of a presented SD-JWT VC or mDoc credential. The wallet leaves this property out for other credential formats.

      property name* any

      Disclosed claims of a presented SD-JWT VC or mDoc credential. The wallet leaves this property out for other credential formats.

    • ]
      • transactionData

      Transaction data from the Authorization Request, as the verifier sent it. The value is normally an array of base64url strings. The holder must approve this data before the wallet sends the presentation. Read transactionDataDecoded to show the data to the holder.

      transactionDataDecoded object[]

      Decoded transaction data. The wallet shows these objects to the holder for approval.

      dataAgreement object

      Data agreement from the Authorization Request. It gives the terms that govern this verification exchange.

      property name* any

      Data agreement from the Authorization Request. It gives the terms that govern this verification exchange.

      legalPidAttestation stringrequired

      Legal Person Identification Data attestation of the verifier. The wallet uses it to check the legal identity of the verifier.

      legalPidAttestationPop stringrequired

      Proof of possession for the Legal Person Identification Data attestation of the verifier.

      legalPidVerified booleanrequired

      true when the wallet checked the Legal Person Identification Data attestation of the verifier and the check passed.

      isVerifiedWithTrustList booleanrequired

      true when the wallet found the verifier in a configured trust list.

      trustServiceProvider object

      Trust Service Provider entry that the wallet used to check the identity of the verifier.

      property name* any

      Trust Service Provider entry that the wallet used to check the identity of the verifier.

      trustAnchor stringrequired

      Possible values: [did:key, x509]

      DID method, or key type, of the trust anchor that the wallet uses for this presentation.

      kid stringrequired

      Key identifier of the key that the wallet uses to sign the Key Binding JWT, or to decrypt the Authorization Response.

      idToken stringrequired

      OpenID Connect ID Token that the wallet sent to the verifier. Present only when responseType is id_token.

      idTokenDecoded object

      Decoded payload of the ID Token that the wallet sent.

      property name* any

      Decoded payload of the ID Token that the wallet sent.

      clientIdScheme stringrequired

      Possible values: [redirect_uri, did, verifier_attestation, x509_san_dns, x509_hash]

      Client ID scheme of the Authorization Request. It sets how the verifier identifies itself to the wallet.

      verifierAttestation stringrequired

      Verifier Attestation JWT from the verifier. It proves that the verifier may ask for the requested credentials.

      dcqlQuery object

      Digital Credentials Query Language (DCQL) query from the Authorization Request. Read credentials[].id from this query to build the credentials array of the send operation. null when the verifier sent a DIF Presentation Exchange definition instead.

      property name* any

      Digital Credentials Query Language (DCQL) query from the Authorization Request. Read credentials[].id from this query to build the credentials array of the send operation. null when the verifier sent a DIF Presentation Exchange definition instead.

      encryptionJwk object

      Public key of the verifier as a JWK. The wallet uses it to encrypt the Authorization Response when the response mode asks for encryption.

      property name* any

      Public key of the verifier as a JWK. The wallet uses it to encrypt the Authorization Response when the response mode asks for encryption.

      encryptedResponseEncValuesSupported string[]

      Possible values: [A128CBC-HS256, A128GCM, A256GCM]

      JWE content encryption algorithms that the verifier accepts for the encrypted Authorization Response.

      encryptionAlgorithm stringrequired

      Possible values: [ECDH-ES]

      JWE key management algorithm that the wallet used to encrypt the Authorization Response. Empty when the response mode does not ask for encryption.

      createdAt numberrequired

      Unix timestamp in seconds when the wallet made this record.

      updatedAt numberrequired

      Unix timestamp in seconds when the wallet last changed this record.

    Loading...
    Last updated on