Implementation considerations

This document provides an overview of key product and user experience (UX) considerations for organizations designing and implementing digital credential solutions using MATTR holding capabilities.

It outlines decisions to make across the credential lifecycle, from claiming through to presentation, and describes how current and upcoming MATTR capabilities can support these choices.

At a high level, credential holding involves three steps:

The issuer offers a credential.
The holder accepts the offer, collects the credential and stores it in a digital wallet application.
The holder later presents it to a verifier when required.

Within this lifecycle, there are several key decisions to make that will shape the user experience and technical implementation.

How is the issuer offering credentials to the user?

Issuers might have multiple methods for offering credentials, each suited to different user experiences and contexts:

QR Code: Generate a QR code that users can scan with their mobile device to initiate the issuance process.
Deep Link: Provide a clickable URL that users can access from an email, mobile browser, or mobile app to start the credential issuance flow.
Silent Push: Credentials can be issued silently to authenticated users within an existing app session, requiring no user interaction.

Your holding solution should be designed to accommodate these various methods of credential offering. Refer to Credential offer interaction options for more details.

How will the issuer issue credentials to the user?

MATTR holding capabilities support claiming credentials via two main issuance workflows, each suited to different use cases and user experiences:

Pre-Authorized Code Flow: In this flow users are not required to authenticate before they can claim the credential. For high assurance credentials, the assumption is that the issuer has already authenticated and authorized the user through other means before sharing the credential offer with them.
- The user will not be required to authenticate before claiming the credential, but it is likely they would only be able to access the credential offer through a secure channel (e.g., inside an existing app session).
- Might be used for silent issuance or updates to existing credentials with no user interaction.
- Optional transaction codes can add 2-factor security.
- Refer to the Pre-Authorized Code Overview for more details.
Authorization Code Flow: In this flow users must authenticate before they can claim the credential. It is typically used when credentials are offered publicly (e.g., via QR code or website).
- The user will be redirected to an authentication provider to authenticate.
- After completing authentication, the user might be redirected to additional custom components as defined by the issuer.
- Refer to the Authorization Code Overview for more details.

Your holding solution should be designed to accommodate these various issuance workflows.

How will the user collect the credential?

When generating a credential offer, issuers can influence which wallet applications are able to claim the offer and how the user experience flows. This involves both user experience considerations and security, privacy, or commercial requirements where you want a specific app to claim the credential:

Open model: Users can use any compatible app to claim the credential.
Restricted model: Users can only use specific apps to claim the credential using unique custom schemes or app links/universal links.

This decision also affects how holder application developers can design the user experience:

Whether users are prompted to select a wallet app when they scan a QR code or click a link, or are taken directly to a specific app.
Whether users can scan a QR code with their device's native camera, or must use an in-app scanner within a specific wallet app.

Refer to Claiming credential offers for more details.

How will you manage credential status?

The issuer configures and publishes a status list that your holding solution can retrieve to determine the current status of a credential. Consider how you will implement this in your solution:

Issuers typically define how often apps should fetch updated status lists using the Time to Live (ttl) and Expiry (exp) parameters:
- ttl: Recommended duration for using a retrieved copy of a status list before retrieving the latest one.
- exp: Retrieved status lists cannot be used after this time.
Apps can rely on cached statuses between TTL and expiry to maintain offline usability. Consider how to balance up-to-date status checking with user experience and app performance.
Consider how to notify users if their credentials are revoked or suspended.

Refer to Credential revocation for more information.

How will users be able to present credentials to verifiers?

Users can present their credentials in person or remotely:

In-Person Presentation (ISO/IEC 18013-5):
- Currently supported via QR code device engagement.
- NFC engagement offers a faster, more intuitive experience and is in development.
- To enable NFC engagement in your iOS apps, we recommend to apply for the Apple entitlement as soon as possible.

Refer to Proximity Presentation to learn more.

Remote Presentation (ISO/IEC 18013-7):
- Supported through OpenID4VP (redirect experience).
- Enables credential presentation in browser or app flows between holders and verifiers.
- MATTR's support for the Digital Credentials API (DC API) is currently available as a tech-preview and offers a more streamlined user experience.

Refer to Remote Presentation to learn more.

How to establish trust with verifiers?

You can manage which relying parties (verifiers) are trusted to request or accept credentials from your users:

The Holder SDK supports configurable trust lists for verifier certificates.
App UX can adapt based on trust level — e.g., blocking untrusted requests or alerting users.
For remote presentations, verifier authentication is mandatory.

How to ensure credentials are only presented by their rightful holders?

Biometric or device-level authentication ensures that credentials are only presented by their rightful holders.
The MATTR Holder SDKs support OS-level biometrics (Face and fingerprint authentication, PIN, passcode, pattern).
Issuers can define per-credential security policies.
Balance security with inclusion, as some users may lack or disable biometrics.

Refer to the Device Key Authentication guide for more information.