#OpenID4VP: A Developer's Guide to Verifiable Presentations

In today's digital world, proving who you are online is often a clumsy and risky process. We're asked to share entire identity documents just to prove a single fact, like our age, leading to oversharing of sensitive personal data. The current landscape relies on centralized identity providers, creating data silos and giving users little control over their own information. This model is not only inefficient but also ripe for phishing and fraud. The solution to this problem is a standardized, decentralized approach to identity verification.

OpenID for Verifiable Presentations (OpenID4VP) is a protocol built on the foundations of OAuth 2.0 that standardizes how a person (a Holder) can present cryptographically secure digital credentials to an online service (a Verifier) in a secure, privacy-preserving, and user-controlled way. It creates a common language for requesting and receiving proof of identity attributes, putting you in control via your digital Wallet and enabling the crucial principle of data minimization.

In essence, OpenID4VP is the technical framework for a digital "show your ID" online, but with the power to show only the specific pieces of information required for a given transaction.

#What is OpenID4VP, Exactly?

To fully grasp the protocol, it's helpful to look at it from a few different angles—from a simple real-world analogy to its formal definition and the key players involved in every interaction.

#In Simple Terms: A Digital "Show Your ID" for the Internet

Imagine you're at a concert venue, and a security guard needs to verify that you are old enough to enter. You pull out your driver's license. The guard looks at your photo to see it's you and checks your date of birth to confirm you're over 21. Critically, they don't need to know your home address or any other attribute on the credential. They verify the one piece of information they need and let you pass. OpenID4VP is the technical framework that enables this exact, privacy-preserving interaction on the internet. It allows a website (Verifier) to ask your digital Wallet for proof of a specific claim (like being over 21), and for your wallet to provide just that proof without revealing your entire digital identity.

#The Official Definition Explained

Formally, OpenID4VP is a protocol that extends standards like OAuth 2.0 and OpenID Connect, enabling users to present Verifiable Presentations (VPs)—which are packages containing one or more Verifiable Credentials (VCs)—to prove claims about themselves.

Let's break down the key components of this definition:

• Extends OAuth 2.0: The protocol is built upon the widly used authorization flows of OAuth 2.0. This is a significant advantage for developers, as it uses a familiar security architecture, reducing the learning curve and making it easier to integrate into existing systems.  
• Verifiable Credentials (VCs): These are the digital equivalents of your physical credentials like a driver's license, a university diploma, or an event ticket. A VC is a set of claims about a subject, issued by a trusted entity (like a government or university), and is cryptographically signed to be tamper-evident. These VCs are stored securely in your digital wallet.  
• Verifiable Presentations (VPs): This is a data package created by your wallet at the moment of presentation. It contains the specific VCs (or just parts of them) that a Verifier has requested. The VP is then digitally signed by you, the Holder, which serves as cryptographic proof of your consent and control over the data being shared in that specific transaction.

#Key Actors: The Verifier, the Holder, and the Wallet

Every OpenID4VP interaction involves three distinct roles, and understanding them is fundamental to understanding the protocol's architecture.

• The Holder: This is you, the end-user. The Holder is the individual who possesses the digital credentials and has ultimate control over their own identity data. You are the subject of the claims being asserted in the VCs.  
• The Verifier (or Relying Party): This is the application, website, or service that needs to verify some piece of information about the Holder. A Verifier could be an e-commerce site checking your age, a bank performing a Know Your Customer (KYC) check, or a venue scanning your digital ticket.  
• The Wallet: This is the software, typically a mobile application, that you use to securely store your VCs, receive verification requests, and manage the presentation process. The Wallet acts as your digital agent, working on your behalf to interpret requests, get your explicit consent, and construct the response for the Verifier.

This three-party model represents a fundamental architectural shift away from traditional, federated identity systems. In a typical "Sign in with Google" flow, the interaction is primarily between you and the Identity Provider (IdP); the service you're accessing simply trusts the IdP. The verifiable credentials model decouples these roles. An Issuer creates the credential, the Holder stores it, and the Verifier consumes it, often without the Issuer being directly involved in the verification transaction at all. This decoupling is the core change. A Verifier doesn't need a pre-existing technical integration with every possible Issuer. Instead, it only needs to be able to verify the cryptographic proof of the credential presented by the Holder, creating a more open, interoperable, and scalable "web of trust".

#How the OpenID4VP Protocol Works (A Step-by-Step Flow)

The OpenID4VP protocol defines a clear, secure sequence of interactions between the Verifier, the Holder, and the Wallet. While the underlying cryptography is complex, the flow itself is logical and designed for a seamless user experience, whether on a single device or across multiple devices (like a laptop and a phone).

The following diagram illustrates the standard cross-device flow, which is the most common implementation.

#Step 1: The Verifier Creates a Presentation Request

The process always begins with the Verifier needing to confirm one or more claims about a user. To do this, it constructs an Authorization Request. At the heart of this request is a presentation_definition or, in the latest specification, a dcql_query, which precisely defines what credentials and claims are needed (e.g., "a government-issued ID that contains a date_of_birth claim"). This request is then encoded into a URL, which is typically presented to the user as a QR code for cross-device interactions or a deep link for same-device flows

#Step 2: The Holder's Wallet Presents the Credentials

The Holder initiates the interaction by scanning the QR code with their Wallet application. The Wallet then takes over as the user's agent:

1. It decodes the URL from the QR code and uses the information to fetch the full Authorization Request object from the Verifier.
2. It parses the request to understand the Verifier's requirements.
3. The Wallet searches its secure storage for any VCs that satisfy the request.
4. Crucially, it prompts the Holder for explicit consent. The user is shown exactly what information is being requested and who is requesting it (e.g., "OnlineStore.com would like to verify you are over 18."). No data is shared without this consent.
5. Once the user approves, the Wallet prepars the presentation. Depending on the credential format:
   • W3C VC: Create a Verifiable Presentation (JWT-VP or Data-Integrity VP) controlled and signed by the Holder.
   • SD-JWT VC: Return the SD-JWT with the selected Disclosures and, if holder binding is required, add a Key Binding JWT.
   • ISO mDL/mdoc (ISO/IEC 18013-7): Return a DeviceResponse, bound to the Verifier’s request through the SessionTranscript and OID4VP hand-over structure.
6. It packages the result into a vp_token (and, if applicable, a presentation_submission) and send it to the Verifier’s HTTPS endpoint using OID4VP’s response_mode=direct_post.

#Step 3: The Verifier Receives and Validates the Presentation

The Wallet’s Authorization Response arrives at the Verifier’s HTTPS endpoint via OID4VP’s response_mode=direct_post. It includes a vp_token (and sometimes a presentation_submission), whose content depends on the credential format.

The Verifier then validates: 1. Holder binding & replay protection: Confirm that nonces and audience values match the request, ensuring the response is fresh and bound to this Verifier. 2. Issuer authenticity: Verify the Issuer’s signatures — on credentials (W3C), the SD-JWT, or mdoc data elements. Resolve trust chains (e.g., via DIDs) where required. 3. Selective disclosure (if applicable): For SD-JWTs, recompute disclosed values against the digests. 4. Claim satisfaction: Ensure the presented data fulfills the Verifier’s original request. 5. Status & validity: Check that credentials or documents have not been revoked, suspended, or expired. 6. Format-specific checks: - W3C VC: Validate the Verifiable Presentation (JWT-VP or Data-Integrity VP) structure. - SD-JWT VC: Validate the Key Binding JWT when holder binding is required. - ISO mDL/mdoc: Validate the SessionTranscript and OID4VP hand-over structure for integrity and replay protection.

If all checks succeed, the Verifier can trust the authenticity, integrity, and freshness of the claims and proceed with the transaction (e.g., granting access or completing a purchase).

#OpenID4VP vs. OpenID4VCI: What's the Difference?

Within the decentralized identity ecosystem, you will frequently encounter two related acronyms: OpenID4VP and OpenID4VCI. While they sound similar and are part of the same family of specifications, they serve two distinct and complementary purposes: presentation and issuance. Understanding the difference is key to understanding the full lifecycle of a verifiable credential.

#OpenID4VCI (Issuance): Minting the Digital Credential

OpenID for Verifiable Credential Issuance (OpenID4VCI) is the protocol used to get a new credential into your wallet in the first place. The primary interaction in this flow is between an Issuer (e.g., a university, government agency, or employer) and the Holder's Wallet. The Issuer uses the OID4VCI protocol to securely offer and deliver a newly created VC to the Holder after they have authenticated and proven their eligibility. You can think of this as the "enrollment" or "credential pickup" phase.

#OpenID4VP (Presentation): Showing the Digital Credential

As we've discussed, OpenID4VP is the protocol for using a credential that is already stored in your wallet. The primary interaction here is between the Holder's Wallet and a Verifier. The Holder uses OpenID4VP to present proof of claims from their existing credentials to a third party that needs to verify them. This is the "verification" or "show your ID" phase.

#How They Work Together in a Decentralized Identity Ecosystem

OID4VCI and OID4VP are not competing standards; they are two sides of the same coin, designed to work together to enable a complete, end-to-end credential lifecycle. A credential has no value if it cannot be both reliably issued and reliably presented.

Consider this complete workflow:

1. Issuance (OID4VCI): You graduate from a university (Issuer). You log into the university's alumni portal and request a digital version of your diploma. The university uses OpenID4VCI to issue a VerifiableDiploma credential directly and securely to your digital Wallet.
2. Presentation (OpenID4VP): Months later, you apply for a job at a new company (Verifier). The company's online application portal requires proof of your degree. The portal generates a request using OpenID4VP. You scan a QR code, and your Wallet uses OpenID4VP to present your VerifiableDiploma to the company for instant, cryptographic verification.

These two protocols are the fundamental pillars of the broader OpenID for Verifiable Credentials (OID4VC) suite, which aims to standardize the entire lifecycle of a digital credential. The combined adoption of both OID4VCI and OID4VP by major initiatives like the EU Digital Identity Wallet demonstrates that a mature, interoperable ecosystem requires standardized solutions for both getting credentials and using them.

#Understanding the Specification: From Drafts to DCQL

Like many open standards, the OpenID4VP specification has evolved over time through a collaborative, public process. This has led to some confusion among developers regarding different draft versions and, most importantly, a significant technical upgrade in how credential requests are made.

#Why Are There So Many Drafts? A Look at the OIDF Process

Standards developed at the OpenID Foundation (OIDF) go through a rigorous, iterative process before being finalized. They are published as a series of numbered "implementer's drafts," which allow the global community of developers, companies, and security experts to build prototypes, provide feedback, and refine the protocol based on real-world testing. This open process is crucial for ensuring that the final v1.0 standard is robust, secure, and, most importantly, interoperable across different wallets and verifier systems, as proven in recent successful interoperability events.

#The Big Change: From Presentation Definition to DCQL

Early drafts of the OpenID4VP specification relied on a mechanism called Presentation Definition to allow Verifiers to specify their credential requirements. This mechanism, which comes from the Decentralized Identity Foundation's (DIF) Presentation Exchange specification, is a declarative JSON format that lets a Verifier describe the credentials it is looking for.

While functional for simple requests, the latest versions of the OpenID4VP specification (starting with Draft 22 in October 2024) have introduced a more powerful and expressive mechanism: the Digital Credentials Query Language (DCQL). The final, stable v1.0 version of the specification includes DCQL as a core, standardized component.

#What is DCQL (Decentralized Query Language)?

DCQL is a JSON-encoded query language designed specifically for requesting Verifiable Presentations. It allows a Verifier to construct precise, structured queries to request credentials that match specific and even complex criteria.

DCQL offers several advantages over the older Presentation Definition approach:

• Greater Expressiveness: DCQL can formulate much more complex and logical queries. For example, a Verifier can use DCQL to ask for "a VerifiableID where the country is 'US' AND an EmployeeCredential where the role is 'Engineer'", all within a single, structured request.
• Standardization: It provides a single, native query language defined within the OpenID4VP specification itself.
• Future-Proofing: DCQL is already being mandated as the required query language in high-assurance industry profiles.

This evolution from Presentation Definition to DCQL signals a critical maturation of the protocol. It represents a shift from simple "credential matching" to sophisticated "verifiable data querying." Early use cases were straightforward: "Do you have a credential of type X?" As the ecosystem and its use cases have grown more complex, the need for a true query language became apparent. DCQL enables a Verifier to treat a user's wallet less like a simple folder of documents and more like a private, queryable, user-controlled database.

#What is a Verifiable Presentation (VP)?

In OpenID4VP, the response is a vp_token —a container that can hold W3C Verifiable Presentations and/or other presentation types depending on the credential format. The spec states that a VP Token “contains one or more Verifiable Presentations and/or Presentations … in the same or different Credential formats,” and supports W3C VCDM, ISO mdoc, and IETF SD-JWT VC. In other words: a VP is central when you use the W3C VC Data Model, but other formats use their own presentation artefacts.

#The Core Components of a W3C Verifiable Presentation (VP)

A W3C Verifiable Presentation is a data structure that packages data from one or more Verifiable Credentials so the authorship is verifiable. Common fields include:

• @context: Specifies the JSON-LD context, which defines the vocabulary and semantics of the data model (e.g., the W3C Verifiable Credentials v1 standard).
• type: An array that declares the object's type, which must include VerifiablePresentation.
• verifiableCredential: An array containing one or more VCs. These can be the full, original VCs or, in the case of selective disclosure, just specific claims from them.
• holder - An identifier for the user (often a Decentralized Identifier (DID)) who is creating and presenting the VP. This identifies who is making the presentation.

For JWT-encoded VPs, the vp claim MUST be present in the JWT payload.

#How the Credential Format changes the “presentation”

#W3C VCDM (e.g., VC-JWT / Data Integrity):

Inside the VP, verifiableCredential can hold VC-JWTs (compact JWTs) or JSON-LD credentials, and the VP is signed by the Holder (e.g., via JWS/JWT or Data Integrity proof). The Data Model details both embedded (Linked Data) and external (JWT) proofs and the required vp claim for JWT VPs.

#SD-JWT VC (IETF):

The presentation is an SD-JWT presentation consisting of the SD-JWT plus selected Disclosures and optionally a KB-JWT for holder binding—not a W3C VP wrapper by default. The IETF draft states: “An SD-JWT consists of … the SD-JWT itself, optional disclosures, and an optional KB-JWT,” and “A presentation of an SD-JWT VC MAY contain a KB-JWT.” OpenID4VP transports this as a Presentation inside the VP Token.

#mDL / mdoc (ISO 18013-5, 18013-7):

OpenID4VP carries the ISO DeviceResponse CBOR structure in the VP Token (again, not a W3C VP). The spec: “The VP Token contains the base64url-encoded DeviceResponse CBOR structure as defined in ISO/IEC 18013-5 ….” ISO/IEC 18013-7 adds over-the-internet presentation via OpenID4VP.

#Example of a JWT-based Verifiable Presentation (JSON Snippet)

{
  // The @context specifies the data model, in this case, the W3C Verifiable Credentials v1 standard.
  "@context": [
    "https://www.w3.org/2018/credentials/v1"
  ],
  // The id provides a unique identifier for this specific presentation instance.
  "id": "Fs2M6HVrER7y",
  // The type array declares that this object is a Verifiable Presentation.
  "type": [
    "VerifiablePresentation"
  ],
  // The holder property contains the Decentralized Identifier (DID) of the user who is presenting the credential.
  "holder": "did:key:z6MkwQx8J3LwFzYjv7Lqk7h2b7Zr5dF6Qe5mQ3E8iJ2o8YkP",
  // This array contains the actual credential(s) being presented. It's a JWT string in this example.
  "verifiableCredential": [
        "eyJraWQiOiJkaWQ6andrOmV5SnJkSGtpT2lKRlF5SXNJ..."
    ]
}

#Real-World OpenID4VP Use Cases & Implementations

The true value of a technical protocol lies in its ability to solve real-world problems. OpenID4VP is already being deployed across various industries to create more secure, efficient, and privacy-preserving user experiences. Use-case examples include:

#Use Case 1: Streamlining KYC for Financial Services

• The Problem: Traditional Know Your Customer (KYC) processes for opening a bank account are notoriously slow, require manual document verification, and force users to upload highly sensitive information, creating a large attack surface for data breaches.
• The OpenID4VP Solution: A bank, acting as a Verifier, can use OpenID4VP to request the necessary claims (e.g., full_name, date_of_birth, address) from a user's government-issued digital ID (like an mDL). The user simply scans a QR code and consents to the data sharing from their Wallet. The bank receives a cryptographically verified and trustworthy attestation in seconds, dramatically reducing onboarding friction, minimizing fraud, and improving regulatory compliance

#Use Case 2: Age Verification for Restricted Content

• The Problem: Websites that sell age-restricted products like alcohol or offer services like online gambling must verify a user's age. Simply asking for a date of birth is not sufficient, but asking for a full ID scan means the user needs to share information that is not directly required (e.g. address).
• The OpenID4VP Solution: An e-commerce site (Verifier) can request a single, boolean claim: is_over_18: true. A user with a digital driver's license in their wallet can selectively disclose only this claim. They prove they meet the age requirement without revealing their name, address, or exact date of birth. This is a perfect example of data minimization in practice, enhancing user privacy while still meeting business needs.

#Use Case 3: Digital Ticketing for Events and Venues

• The Problem: Traditional paper tickets or simple QR codes are easy to counterfeit, scalp, or fraudulently resell, leading to revenue loss for organizers and frustration for attendees.
• The OpenID4VP Solution: An event organizer (Issuer) uses OID4VCI to issue a Verifiable Credential as a ticket, which is cryptographically bound to the purchaser's identity (Holder). When the attendee arrives at the venue (Verifier), they present the ticket from their wallet using OpenID4VP. The scanner at the gate can instantly verify the ticket's authenticity, confirm that it has not been used before, and ensure that it is being presented by its legitimate owner, effectively eliminating ticket fraud.

#Practical Implementation: A Hands-On Walkthrough

For a developer building a service that needs to verify user data, implementing OpenID4VP involves creating the request and handling the response. Here is a high-level walkthrough of the Verifier's role in the process.

#Step 1: Define What You Need (DCQL)

The first step for any Verifier is to precisely define the data it needs to request. With the finalization of the v1.0 specification, DCQL is the modern, standard way to construct this query. You would create a JSON object that specifies the credential types, formats, and specific claims you require. Numerous open-source libraries and tools are emerging to help build and validate these DCQL queries programmatically.

You can for example, explore the walt.id's open-source verifier here, which let's you request and validate credentials via UI, API & SDKs.

#Step 2: Generate a Presentation Request and Present it via a UI (QR Code Flow)

This is the most common flow for web applications interacting with a user's mobile wallet.

1. Your backend service generates the full Authorization Request, including the DCQL query, a unique cryptographic nonce to prevent replay attacks, and the response_uri where the wallet should send the final VP.
2. Your service then creates a request_uri that points to this full request object.
3. Your frontend application takes this request_uri and embeds it into a standardized URL with the scheme openid4vp://. This complete URL is then rendered as a QR code on the screen for the user to scan with their wallet app.

You can experience this in action by trying out the open-source walt.id verifier portal here.

#Step 3: Generate a Presentation Request via API and Send it as a Direct Link (Same-Device Flow)

In this flow, a backend service constructus the Authorization Request and sends it to the user as a link, in for example an email.

1. Your application constructs the openid4vp:// URL containing the request_uri just as in the cross-device flow.
2. Instead of rendering a QR code, your app uses a deep link to invoke the user's installed wallet app directly, passing the request parameters seamlessly. The wallet opens, prompts the user for consent, and returns the response to your application, all within a smooth, in-app workflow.

You can use the walt.id open-source Verifier API to handle the Authorization Request creation and perform various checks on presented credentials. Learn more here.

#OpenID4VP FAQ

#What is the OpenID standard?

The OpenID Foundation (OIDF) is a non-profit international standards body that develops open, interoperable standards for digital identity. Its most famous standard is OpenID Connect, which is used by billions of people for secure logins across the web, but it also maintains the entire OpenID for Verifiable Credentials (OID4VC) family of specifications, including OpenID4VP.

#Is OpenID4VP the same as OpenID Connect?

No. OpenID Connect is an identity layer on top of OAuth 2.0 used to authenticate the End-User and optionally return claims. OpenID4VP is a separate OpenID Foundation specification that defines a mechanism on top of OAuth 2.0 to request and deliver presentations of credentials (often via a user’s Wallet). Both reuse OAuth 2.0, but their primary goals differ: OIDC = authentication, OID4VP = credential presentation.

#Where does OpenID4VP fit in the Self-Sovereign Identity (SSI) model?

Self-Sovereign Identity (SSI) is a conceptual model for digital identity that puts individuals in complete control of their own personal data, independent of any central authority. OpenID4VP is a crucial piece of the technical implementation that makes the SSI vision a reality. It provides the standardized, interoperable protocol that allows a user (Holder) to exercise their sovereign control by selectively sharing their data from their personal Wallet with Verifiers. It is a key specification that makes the principles of SSI practical, secure, and ready for widespread adoption.

#Next steps

• OID4VCI - Explore the protocol Issuers use in more detail.
• How to verify a Verifiable Credential via OID4VP - Checkout the walt.id Verifier API docs for verifying a VC via OID4VCP.