Skip to main content

OpenID4VCI

OpenID for Verifiable Credential Issuance (OpenID4VCI) is a protocol that defines how digital wallets can request and receive verifiable credentials from credential issuers using OAuth 2.0-based flows. It extends standard OAuth authorization patterns to handle the specific requirements of credential issuance, including support for multiple credential formats, batch issuance, and various authorization methods. The protocol enables secure, standardized communication between wallets and issuers while allowing flexibility in authentication mechanisms and credential types, making it suitable for a wide range of digital identity use cases.

Flow overview​

All flows require the wallet – the client application – to obtain an access token from an authorization server and to present this access token to the credential issuer to receive a credential. The key difference between the flows lies in when and how the issuer establishes the recipient's identity:

  • Pre-Authorized Code Flow: Used when the issuer already knows and has verified the identity of the credential recipient before initiating the flow. The issuer can confidently deliver the credential offer directly to the intended person.

  • Authorization Code Flow: Used when the credential offer may be accessed by unknown parties, such as through publicly displayed QR codes or shared links. The issuer must authenticate and verify the identity of whoever initiates the flow before issuing credentials.

The choice between flows depends on your distribution method and trust relationship with recipients at the point of credential offer.

Pre-Authorized Code Flow​

The Pre-Authorized Code Flow begins when the issuer directly provides a pre-authorized code to the wallet through a credential offer. This offer contains both details about the available credential(s) and the pre-authorized code that grants access to them. The wallet presents this pre-authorized code directly to the authorization server's token endpoint, bypassing the traditional authorization step, and receives an access token in return. The wallet then exchanges this access token at the issuer's credential endpoint for the actual verifiable credential.

Since the issuer provides the pre-authorized code directly to the wallet, this flow works best when the issuer can confidently verify the code is reaching the intended recipient. This applies in scenarios such as:

  • The wallet holder is physically present and has been verified through in-person authentication processes
  • The pre-authorized code is provided to a user within a platform where they have already completed robust authentication during login

To enhance security, the issuer can require a transaction code (tx_code) that is delivered through a separate communication channel such as SMS, email, or secure messaging. The user must enter this transaction code during the credential issuance process, providing an additional layer of verification that the legitimate recipient is completing the flow.

The specific scenarios where you should use this flow depend on your security requirements, particularly your required Level of Assurance (LoA). This flow is ideal for situations where the issuer has already established trust with the recipient through other means and wants to streamline the credential issuance process.

Authorization Code Flow​

The Authorization Code Flow is initiated either by the wallet or by the issuer:

  • Wallet-initiated: The end user selects an offered credential from within their wallet. The credential may be pre-configured in the wallet's offerings, or discovered through published credential offerings or guidance from a verifier's request for credential data.
  • Issuer-initiated: The issuer proactivaly sends a credential offer to the wallet holder, typically through a QR code scan, deep link, or URL. The offer specifies one or more credentials the issuer is prepared to issue to the wallet holder.

In both cases, the wallet first retrieves the issuer's metadata to understand supported credential types and authorization requirements. The wallet then sends an authorization request to the issuer's authorization server. The authorization server processes this request through a configurable authorization flow, which may include user authentication (such as login credentials, biometrics, or multi-factor authentication), identity verification, eligibility checks, and explicit user consent for credential issuance.

Upon successful authorization, the server responds with an authorization code sent to the wallet. The wallet exchanges this authorization code at the token endpoint for an access token. Finally, the wallet presents the access token to the issuer's credential endpoint to receive the actual verifiable credential.

Since this flow supports flexible authorization processes that can be tailored to specific security and business requirements, it accommodates diverse use cases from low-assurance scenarios to high-security credential issuance requiring strong authentication and verification.