Verify a credential
This guide sends a verification request to the credential verifier and reads the signed attestation that comes back. You create a transaction, let a wallet present a credential, and then ask the verifier to check the presentation.
The example uses the Annex A profile and a proof-of-age credential.
Prerequisites
- A running verifier with mutual TLS enabled. See install and run the server and configure TLS.
- A client certificate that the verifier trusts. The examples use
certificates/tls/ewqwe.user1.cert.pem. - A wallet that can present a credential to the verifier, such as the EUDI Wallet or the AV app. See test with the EUDI wallet or test with the AV app.
jqfor the JSON extraction steps.
Run the commands from the repository root, so that the relative certificate paths resolve.
Understand the request pattern
The verifier separates the wallet interaction from the check. You set up a transaction first, the wallet answers that transaction, and you then send the presentation for verification. Three endpoints carry the pattern:
| Step | Endpoint | Who calls it | What it does |
|---|---|---|---|
| Create a transaction | POST /ewqwe_api/openid4vp/init | Relying party | Stores the nonce and the request. |
| Read the transaction | GET /ewqwe_api/openid4vp/status/{id} | Relying party | Returns the presentation from the wallet. |
| Verify the presentation | POST /ewqwe_api/verify | Relying party | Runs the checks and signs the attestation. |
Set up shared values for the commands below.
CERT=certificates/tls/ewqwe.user1.cert.pem
KEY=certificates/tls/ewqwe.user1.key.pem
BASE=https://localhost:9443
Steps
-
Create the transaction. The server builds the wallet callback URL from
public_root_url, so that value must be reachable by the wallet and must match a DNS subject alternative name of the server certificate. Thestatevalue is yours to choose; the verifier binds it to the transaction and expects it again at verification.curl -sk --cert "$CERT" --key "$KEY" \ -H "Content-Type: application/json" \ -d '{ "profile": "annex-a", "credential_type": "proof-of-age", "state": "demo-state-0001" }' \ "$BASE/ewqwe_api/openid4vp/init" | tee init.jsonExpected output:
{ "transaction_id": "6f1c8a2e-...", "client_id": "redirect_uri:https://localhost:9443/ewqwe_api/openid4vp/direct_post", "client_id_scheme": "redirect_uri", "request_uri": "https://localhost:9443/ewqwe_api/openid4vp/request/6f1c8a2e-...", "authorization_request_uri": "av://?client_id=...&response_type=vp_token&...", "expires_in": 300, "profile": "annex-a" } -
Extract the transaction values for later steps.
TRANSACTION_ID="$(jq -r .transaction_id init.json)" CLIENT_ID="$(jq -r .client_id init.json)" -
Present the credential with a wallet. Give the wallet the
authorization_request_urifrom the previous response, as a QR code or as a deep link. The wallet sends the presentation to the verifierresponse_uri, and the verifier stores it in the transaction. Follow test with the EUDI wallet or test with the AV app for this step. -
Read the transaction status. Repeat this call until
statusisreceived.curl -sk --cert "$CERT" --key "$KEY" \ "$BASE/ewqwe_api/openid4vp/status/$TRANSACTION_ID" | tee status.jsonExpected output when the wallet has answered:
{ "status": "received", "authorization_response": { "vp_token": "{\"proof_of_age\":[\"b3JnLmlzby4x...\"]}", "presentation_submission": null, "state": "demo-state-0001" }, "nonce": "X9d2..." }The
statusvalue ispendinguntil the wallet answers, and thenreceived. A wallet that sends an error response instead of a presentation sets the status toerror. -
Extract the presentation and the state.
STATE="$(jq -r .authorization_response.state status.json)" VP_TOKEN="$(jq -r .authorization_response.vp_token status.json)" -
Send the presentation for verification. The
statemust match the transaction, and theclient_idmust match the value from the init response.jq -n --arg vp "$VP_TOKEN" --arg st "$STATE" --arg cid "$CLIENT_ID" \ '{vp_token: $vp, presentation_submission: null, state: $st, client_id: $cid}' \ > verify_request.json curl -sk --cert "$CERT" --key "$KEY" \ -H "Content-Type: application/json" \ --data @verify_request.json \ "$BASE/ewqwe_api/verify" | tee verify_response.jsonExpected output when the checks pass:
{ "success": true, "message": "Credential verified successfully", "verification_details": { "signature_valid": true, "not_expired": true, "issuer_trusted": true }, "attestation": "eyJhbGciOiJFUzI1NiIsImtpZCI6..." }Expected output when a check fails. An mDoc presentation returns HTTP
400with the reason as a JSON string, because the verifier cannot return a partial result for an mDoc."bad request: mDoc issuerAuth certificate chain is not trusted: the issuer CA is not in the trusted certificates directory"An SD-JWT VC behaves differently. The endpoint returns HTTP
200withsuccessfalse, and the attestation records the failure without the claims.{ "success": false, "message": "Credential verification failed", "verification_details": { "signature_valid": false, "not_expired": true, "issuer_trusted": false }, "attestation": "eyJhbGciOiJFUzI1NiIsImtpZCI6...", "errors": ["Issuer certificate does not chain to a trusted CA"] } -
Read the attestation. Decode the payload of the JWT to inspect the verified claims.
ATTESTATION="$(jq -r .attestation verify_response.json)" python3 -c "import base64, json, sys; p = sys.argv[1].split('.')[1]; print(json.dumps(json.loads(base64.urlsafe_b64decode(p + '=' * (-len(p) % 4))), indent=2))" "$ATTESTATION"Expected payload for a successful proof-of-age verification. The exact values depend on the credential and the transaction.
{ "iss": "ewqwe.acme.com", "sub": "6f1c8a2e-...", "aud": "redirect_uri:https://localhost:9443/ewqwe_api/openid4vp/direct_post", "iat": 1770000000, "nbf": 1769999995, "exp": 1770000300, "jti": "550e8400-e29b-41d4-a716-446655440000", "verified": true, "nonce": "X9d2...", "doc_type": "eu.europa.ec.av.1", "namespace": "eu.europa.ec.av.1", "age_over_18": true }The
issclaim is the common name of the attestation signing certificate. Thejticlaim is unique to this attestation, so you can use it as an idempotency key. -
Verify the attestation signature. The JWKS endpoint is public and returns the attestation key together with the
kidthat appears in the JWT header.curl -sk "$BASE/ewqwe_api/openid4vp/.well-known/jwks.json"Select the key whose
kidequals thekidof the attestation, and verify the JWT signature with that key. For the claim list, see attestations. -
Confirm that the transaction is consumed. Send the same request body again.
curl -sk --cert "$CERT" --key "$KEY" \ -H "Content-Type: application/json" \ --data @verify_request.json \ "$BASE/ewqwe_api/verify"An mDoc presentation now returns
400withstate is required for mDoc verification, because the verifier consumed the stored transaction and no longer has the request context to rebuild the session transcript.
Troubleshooting
- The response is
401 Unauthorized. The request carried no client certificate. Add--certand--key. - The response is
404with{"error": "..."}. The transaction id is unknown, or you created the transaction against another server instance. - The response is
410 Gone. The transaction exceededtransaction_ttl_secsand expired. Create a new transaction. - The response is
400withclient_id does not match the transaction-bound request. Send theclient_idvalue from the init response. - The response is
400withstate is required for mDoc verification. An mDoc presentation needs the transaction, so includestate. - The response is
400with an untrusted-issuer message. The issuer CA of the credential is not inissuers_cas_dir. Add the CA file and restart the server, because the directory is read only at startup. - The response is
400with a decode message. Thevp_tokenis not a valid SD-JWT VC, mDocDeviceResponse, or direct JSON presentation. Check that you copied the value without truncation. successisfalsewith a nonce mismatch error. The presentation does not belong to the transaction thatstatenames. Use thevp_tokenand thestatefrom the same status response.- The status stays
pending. The wallet did not reach theresponse_uri. Check that the wallet can reachpublic_root_urland that the wallet trusts the server certificate. - The response is
500and the log shows a journal error. The checks passed but the journal write failed. See configure storage.
Next steps
- Read the endpoint reference in the HTTP API reference.
- Read the check sequence in the verification process.