The need for seamless and secure credential issuance is more pressing than ever. From digital ID cards to permits and proofs of eligibility, organizations are looking for ways to deliver trusted digital experiences that feel intuitive for users and integrate smoothly with existing systems.
That is where OpenID for Verifiable Credential Issuance, or OID4VCI, comes in.
What is OID4VCI?
OID4VCI is an open standard that defines how digital credentials, such as a driver’s license or a residency card, can be issued in a secure, consent-based, and privacy-preserving way. It builds on widely adopted internet protocols such as OAuth 2.0 and OpenID Connect. This makes it familiar to developers and easy to integrate into existing systems.
More importantly, OID4VCI is designed with flexibility in mind. It recognises that not every credential issuance should look the same. Different contexts require different flows.
Two flows with one goal: trust through choice
OID4VCI supports two primary patterns for issuing credentials:
- The authorization code flow
- The pre-authorized code flow
At first glance, they may sound similar. However, they differ in how and when the user is authenticated, which affects how the credential offer is shared and who can access it.
The authorization code flow: Open access, secure claim
This flow allows an issuer to create a long-lived credential offer that can be presented to any user. The key requirement is that the user must authenticate themselves to claim the credential.
This is generally used when the offer is publicly accessible, and the issuer cannot assume who the user is in advance. Authentication ensures the user is identified and that data can be dynamically pulled to personalize the credential.
This flow typically involves setting up connections to an authentication provider and a claims source. Once configured, the issuer can generate reusable credential offers. When a user interacts with the offer, they are guided through an authentication step. After successful authentication, the issuer can retrieve the required claims for that particular user and issue the credential.
This pattern is ideal when issuers want to support open access to credential offers while still maintaining assurance and flexibility.
The pre-authorized code flow: Trusted handoff
This flow is used when the issuer already knows who the user is and has authenticated them outside of the issuance process. The offer is created for a specific user and shared through a secure channel, such as a logged-in web portal, email, or SMS.
Unlike the authorization code flow, this option does not require the user to authenticate again during credential issuance. However, it still supports optional interactive steps such as consent screens, transaction codes, or QR-based claiming, based on the intended use-case.
An issuer uses their own process to verify the user's identity and eligibility, then when satisfied creates a pre-authorized credential offer by providing the relevant user claims data. This claim data is embedded directly into the offer.
The user interacts with the offer to retrieve their credential. If additional security is needed, a transaction code can be configured to act as a second factor, similar to a PIN or MFA step.
When to use which: Business cases and considerations
The key distinction between the two flows is whether the user is already authenticated before the offer is presented.
Use the authorization code flow when you want to make a credential offer available to any user and require them to authenticate before they can claim it. The issuer must have an identity provider integrated and typically uses a claim source to pull data after authentication.
Use the pre-authorized code flow when the issuer already knows and trusts the identity of the user. This allows offers to be shared directly through secure, private channels without requiring the user to authenticate again. It also simplifies integration by allowing claim data to be passed directly when generating the offer.
Each approach has trade-offs. Authorization code flows offer flexibility and public access, but they require more integration and steps. Pre-authorized flows offer speed and control, but rely on strong identity checks before the offer is shared.
How it works behind the scenes
Both flows rely on a common foundation. The issuer creates a credential offer, which acts as an invitation for the wallet to begin the issuance process. This offer contains metadata and endpoints that guide the wallet through the steps required to request and receive a credential.
From this shared starting point, the two flows differ in how the user obtains the access token needed to retrieve the credential.
In the authorization code flow, the offer is shared broadly and the user is unknown until they authenticate. The user is redirected to the issuer’s authentication provider where they complete authentication and receive an authorization code. The wallet exchanges this code for an access token, which is then used to request the credential. This approach allows for dynamic data retrieval based on who authenticated.
In the pre-authorized code flow, the user has already been authenticated and verified before the offer is created. The credential offer includes a pre-authorized code, allowing the wallet to skip the authentication step and go straight to requesting an access token. If configured, a transaction code must also be entered along with the pre-authorized code. This serves as an additional layer of security, much like a second factor in multi-factor authentication.
Once the access token is obtained, either through the authorization code or the pre-authorized code, the wallet uses it to retrieve the credential from the issuer’s endpoint. Both flows use the same infrastructure, but are designed for different issuance strategies.
Ready to try it out?
Sign up for a MATTR VII trial and start issuing verifiable credentials in minutes. Our platform supports both OID4VCI flows and provides everything you need, from credential configuration to user authentication and secure delivery. Explore our guides and tutorials to walk through each step and see how easily you can bring trusted digital experiences to life.
