Credential claiming

Overview

Claiming a credential is the process of receiving a verifiable credential into a digital wallet. From the perspective of a holder (and wallet app developer), this is the core capability that enables individuals to collect and manage their digital credentials, such as identity documents, membership cards, or certifications.

Where issuers are responsible for creating and signing the credential, the holder’s role is to accept, retrieve, and store the credential securely. Claiming ensures the credential can later be presented to verifiers in a way that is trusted, privacy-preserving, and interoperable.

When a user claims a credential, they are:

1. Receiving an offer from an issuer — typically in the form of a QR code, deep link, or push notification.
2. Reviewing details about the issuer and the credential type before deciding to proceed.
3. Authorizing retrieval (through authentication, a pre-authorized code, or other mechanisms depending on the workflow).
4. Requesting and retrieving the credential from the issuer.
5. Storing the credential in their wallet, ready to be presented later to verifiers.

OID4VCI

The OpenID4VCI specification is an open standard developed by the OpenID Foundation, defining how digital wallets can receive verifiable credentials from credential issuers in a secure and interoperable way. It leverages the widely adopted OAuth 2.0 and OpenID Connect to establish a trust framework for credential issuance, ensuring both privacy and user control.

Workflows

OID4VCI defines two distinct workflows, each tailored to different use cases and requirements:

• Authorization Code flow: This interactive, user-driven flow requires the credential recipient (typically a wallet) to redirect the user to the issuer (such as a government or organization) for authentication. After the user successfully authenticates and gives consent, the issuer's authentication provider returns an authorization code. The wallet then exchanges this code for an access token, which is used to obtain the credential.

  The following credential formats can be claimed via the Authorization Code flow:

  • CWT
  • Semantic CWT
  • JSON
  • mDocs

• Pre-authorized Code flow: In this flow, the issuer prepares the credential issuance in advance and may authenticate and authorize the holder ahead of time. Instead of obtaining an authorization code through user authentication, the wallet receives a pre-authorized code directly from the issuer, often via an out-of-band method. The user does not need to authenticate again and the wallet presents the pre-authorized code to retrieve an access token and then claim the credential. For added security, the issuer can require a transaction code (shared separately with the holder) which the wallet must also provide to claim the credential.

  The Pre-authorized Code flow is only supported for mDocs.

MATTR VII supports both workflows, allowing you to choose the one that best fits your use case.