Credential issuance

Overview

When a user scans a credential offer QR code or follows a credential offer deeplink, it triggers the credential issuance flow. This flow enables wallets to securely claim and receive verifiable credentials from MATTR VII issuer tenants.

Issuance Flow

The credential issuance flow is based on the OpenID for Verifiable Credential Issuance (OID4VCI) specification. MATTR VII supports both the Pre-authorized Code and Authorization Code flows.

Pre-authorized Code Flow

In the Pre-authorized Code flow, the authorization code is embedded directly in the credential offer, allowing immediate credential issuance without additional user authentication:

1. As the user scans the QR code or follows the deeplink, a wallet application registered to handle that URL is invoked.
2. The wallet extracts the issuer metadata endpoint URL from the credential offer and queries it to discover the issuer's configuration, including the token and credential endpoint URLs.
3. The wallet uses the authorization code found in the credential offer to make a request to the token endpoint and exchange the code for an access token.
4. The wallet uses the access token returned by the token endpoint to request credential issuance from the credential endpoint.
5. The credential endpoint creates the credential based on the credential configuration defined in the credential offer and responds with the signed credential.

Authorization Code Flow

In the Authorization Code flow, the user must authenticate with a configured authentication provider before receiving the authorization code:

1. As the user scans the QR code or follows the deeplink, a wallet application registered to handle that URL is invoked.
2. The wallet extracts the issuer metadata endpoint URL from the credential offer and queries it to discover the issuer's configuration, including the authorize, token, and credential endpoint URLs.
3. The wallet calls the authorize endpoint, which redirects the user to the configured authentication provider in a webview. Note that only registered wallets can call this endpoint and initiate the authentication process.
4. After completing authentication, the user is redirected by the authentication provider back to the redirect URI configured when making the request to the authorize endpoint. This redirect URI is a path in the wallet that can extract the authorization code from the response returned by the authentication provider following successful authentication.
5. The wallet uses the authorization code to make a request to the token endpoint and exchange the code for an access token.
6. The wallet uses the access token returned by the token endpoint to request credential issuance from the credential endpoint.
7. The credential endpoint creates the credential based on the credential configuration defined in the credential offer and responds with the signed credential.

Flow Diagram

The following diagram illustrates both the Pre-authorized Code flow and Authorization Code flow:

Implementation Options

Using MATTR Holding Capabilities

When using MATTR's holding capabilities, this entire interaction is orchestrated by our holder SDKs. The SDKs handle the complex protocol flows automatically, managing authorization, token exchange, and credential retrieval on behalf of your wallet application.

Building Your Own Wallet

Customers building their own wallet implementations can still claim credentials from MATTR VII issuer tenants by calling the OID4VCI endpoints directly. This approach gives you full control over the wallet experience while maintaining interoperability with MATTR's issuing infrastructure.

Encryption

In some credential issuance scenarios, a wallet application's backend server acts as a proxy or middleman between the credential issuer (MATTR VII) and individual wallet app instances. In these architectures, the credential response passes through the wallet provider's backend infrastructure before reaching the specific wallet instance on a user's device.

To ensure the security and privacy of credentials in such scenarios, MATTR VII supports End-to-End Encryption (E2E Encryption) for credential issuance. This means that both the request to issue a credential and the response which includes the issued credentials can be encrypted in a way that only the intended recipient can decrypt and access them, even if they pass through intermediary servers. For more information, see End-to-End Encryption.