Skip to main content

OpenID4VP - Receive and Present Credential

The Wallet Unit (WU) enables an organisation to present the credentials it holds, much like a person shows a document from a physical wallet. With the Organisation Wallet Suite, your organisation responds to verifiers using OpenID for Verifiable Presentations (OpenID4VP) 1.0 and the Digital Credentials Query Language (DCQL). The holder shares only the credentials and claims that the verifier requests, and only after approving them.

The flow has three steps: receive the verifier's request, find the matching credentials, and send the presentation.

Prerequisites​

  • An API key of your main organisation. See Get API Keys. Sandbox organisations do not have a holder wallet, so they hold no credentials to present.
  • An operational wallet unit, as for receiving credentials.
  • Credentials in the wallet that match the verifier's request.

Step 1: Receive the Request​

Send the openid4vp:// Authorization Request URI that the holder scanned or opened to Receive verification:

curl -X POST "https://demo-api.igrant.io/v4/config/ows/holder/presentations" \
-H "Authorization: ApiKey <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"requestUrl": "openid4vp://?client_id=x509_hash%3AUvRWsFzWB2aL6mJq0YxT3cK9dP4eN8hG1iA5bC7fE2s&request_uri=https%3A%2F%2Fverifier.example.com%2Frequest%2F8f2b1c9e"}'

Example response (200, shortened):

{
"presentation": {
"presentationId": "3f2a7c18-9b4e-4d0a-8c6f-1e5b2a9d4c73",
"status": "presentation_pending",
"clientIdScheme": "x509_hash",
"clientMetadata": { "clientName": "Example Verifier", "logoUri": null, "location": "Sweden", "coverUri": null, "description": "" },
"relyingPartyTrustedListCheck": { "verified": true, "result": "trusted", "role": "access_certificate_provider", "entry": { "status": "granted", "roles": ["access_certificate_provider"], "source": { "id": "5b1e9c2a-7d4f-4e8a-9b3c-2f6d8a0e4c17", "name": "EU access certificate providers", "kind": "etsi_lote", "url": "https://example.eu/lists/access-certificate-providers.xml" } }, "reason": null },
"dcqlQuery": {
"credentials": [
{ "id": "pid", "format": "dc+sd-jwt", "meta": { "vct_values": ["urn:eudi:pid:1"] }, "claims": [{ "path": ["family_name"] }] }
]
},
"transactionDataDecoded": null
}
}

Show the verifier details, and any transactionDataDecoded, to the holder before you continue. Copy the presentationId for the next steps.

Step 2: Find the Matching Credentials​

To find the credentials that match the request, call Filter verification. The request has no body:

curl -X POST "https://demo-api.igrant.io/v4/config/ows/holder/presentations/3f2a7c18-9b4e-4d0a-8c6f-1e5b2a9d4c73/matching-credentials" \
-H "Authorization: ApiKey <YOUR_API_KEY>"

Example response (200, shortened):

{
"credentials": [
{
"id": "pid",
"matchedCredentials": [
{ "credentialId": "d29a6c1e-4b8f-4a1d-9c3e-7f5b2a0d8e11", "vct": "urn:eudi:pid:1", "match": { "family_name": "Andersson" } }
]
}
]
}

The response has one entry for each credential query, and an empty matchedCredentials means that the wallet holds no credential for that query. If the query offers claim options, each matching credential lists the options it can satisfy in claimSets. An entry also has multiple when the query accepts more than one credential.

Step 3: Send the Presentation​

Send the credentials that the holder selected with Send verification, with one entry for each credential query:

curl -X POST "https://demo-api.igrant.io/v4/config/ows/holder/presentations/3f2a7c18-9b4e-4d0a-8c6f-1e5b2a9d4c73/response" \
-H "Authorization: ApiKey <YOUR_API_KEY>" \
-H "Content-Type: application/json" \
-d '{"credentials": [{"id": "pid", "credentialId": "d29a6c1e-4b8f-4a1d-9c3e-7f5b2a0d8e11"}]}'
  • For a query with multiple, use credentialIds instead of credentialId.
  • For a query with claim options, add claimIds with one of the claimSets options of the selected credential.

When the presentation succeeds, status is presentation_acked. If responseRedirectUri is not empty, redirect the user's browser to that address to complete the flow at the verifier.

To decline the request, delete the presentation record. The wallet then tells the verifier that the holder declined, so the verifier does not keep waiting.

Trust status of the verifier

When you switch on requiresTrustedRelyingParty in the holder configuration, the wallet checks the signer of each request against the trust sources in acceptedRelyingParties (for the role access_certificate_provider) and does not respond to a verifier that is not trusted. The result is in relyingPartyTrustedListCheck of the presentation record; with the switch off, no check runs and the value has the reason.code not_required. The wallet also rejects a request with an etsi_tl item that names a list outside acceptedEtsiTrustedLists, and tells the verifier with access_denied and the reason. If the verifier cannot be matched, the Data Wallet shows a "Service provider not verified" warning. See The "Service provider not verified" notice and Trust in the Wallet Ecosystem.