Skip to main content

OpenID4VP (Credential Verification)

OpenID4VP (OpenID for Verifiable Presentations) is the OpenID Foundation protocol that defines how a verifier requests credentials from a holder's wallet, and how the wallet responds with a Verifiable Presentation (VP).

iDen2's Verification Gateway implements OpenID4VP for you. Your backend creates a session, displays a QR code, and polls for the result. The protocol exchange happens between the wallet and Verification Gateway.

The flow​

The four building blocks​

1. Authorization request​

The authorizationUrl (openid4vp://authorize?...) is the verifier's request to the wallet. It carries the response type (vp_token), a client_id used for KB-JWT audience validation, the session state, and client_metadata containing your verifier_member_id — the identity wallets use to look up and display your organisation from the Trust Network on the consent screen. You never build this URL yourself; Verification Gateway returns it ready to render.

2. Presentation definition and JAR​

A DIF Presentation Exchange document describing which credentials and which fields you're requesting. The wallet fetches it as a JWT Authorization Request (JAR, RFC 9101):

GET /openid4vc/request/{sessionId} returns a signed Request Object JWT containing the full authorization request — including the presentation definition — rather than embedding parameters inline in the authorization URL. Verification Gateway signs this JWT with its Ed25519 key. The wallet verifies the signature using GET /.well-known/jwks.json before processing the request.

This matters for two reasons: it gives the authorization request cryptographic integrity (the wallet knows the request is from Verification Gateway and hasn't been tampered with), and it removes the practical limits of encoding everything into a URL query string.

Your verifier configuration determines which presentation definition a session uses (presentationDefinitionId). See Mobile Wallet & Wallet API.

3. VP token​

The wallet's response: an SD-JWT Verifiable Presentation containing the credential with only the consented disclosures attached. The wallet submits it to POST /openid4vc/verify/{sessionId}.

4. KB-JWT (Key Binding JWT)​

A short-lived JWT signed by the holder's key, embedded in the presentation. It proves the presenter actually controls the key the credential was bound to at issuance — preventing replay of a stolen credential. Its aud (audience) claim must match the verifier's client_id, which is why client_id exists separately from verifier_member_id.

What Verification Gateway verifies for you​

When the VP token arrives, Verification Gateway checks the credential signature, the KB-JWT holder binding, issuer membership in your trust network, revocation status, expiry, and policy compliance — then exposes the outcome as verificationResult with per-check detail in checks[]. You read the result with GET /sessions/{sessionId}.

Where to go next​