How to add digital credential holding to your mobile app

Adding digital credential holding to your mobile app means your users can receive, store, and present verifiable credentials—such as mobile driver's licenses, employee badges, or proof-of-age tokens—without leaving your application. This guide helps product and engineering teams understand the integration approach, key decisions, and available tooling.

SDK or ready-made wallet?

Before diving into integration, decide which path suits your product strategy.

MATTR Pi Holder SDK — build it into your app

Best for: teams that want credential holding embedded within their existing mobile application, with full control over the user experience and branding.

The MATTR Pi mDocs Holder SDK provides native libraries for iOS, Android, and React Native. You integrate the SDK into your existing codebase, and your app gains the ability to claim, store, and present credentials directly.

Choose the SDK when you:

• Already have a mobile app and want to add credential capabilities to it.
• Need full control over the user interface and interaction flow.
• Want credential holding to be seamless within your existing app experience.
• Need to customize presentation consent screens, credential displays, or notification handling.
• Are building a purpose-specific application (e.g., employee app, government services app).

MATTR GO Hold — use a ready-made wallet

Best for: teams that want to offer credential holding without building or maintaining a custom wallet, or that need a wallet for testing and pilot deployments.

MATTR GO Hold is a downloadable wallet application that supports credential claiming and presentation out of the box. It can serve as a white-label starting point or a production wallet for end users.

Choose MATTR GO Hold when you:

• Want to get to market quickly without custom mobile development.
• Need a wallet for pilot programs, proofs of concept, or testing.
• Don't require deep integration with an existing app experience.
• Want a standalone wallet app for your users.
• Need a reference implementation to guide your own SDK integration later.

Comparison

Platform requirements

If you're integrating the MATTR Pi Holder SDK, ensure your app meets these minimum requirements:

Core capabilities to integrate

The SDK provides three main capability areas that map to the credential lifecycle.

Credential claiming

Your app receives credential offers (via QR code scan, deep link, or silent push) and claims them using the OID4VCI protocol.

What you implement:

• Handle incoming credential offer URIs (QR scanner, deep link handler, or push notification).
• Trigger the SDK's claiming flow with the offer URI.
• Display claiming progress and result to the user.
• Store credentials securely (handled by the SDK).

Key decisions:

• Which offer channels to support (QR, deep link, push).
• How to surface the claiming experience in your app's navigation.
• Whether to show credential details before accepting.
• Whether your app uses an open model (any compatible wallet can claim) or a restricted model (only your app can claim via custom URI schemes or App Links/Universal Links). This affects whether users can scan QR codes with the device's native camera or must use your in-app scanner.
• Whether the issuer requires wallet attestation. If enabled, your app must implement cryptographic attestation proofs to demonstrate its authenticity before claiming credentials. This requires integration with your wallet backend to issue attestation JWTs.

See claiming credential offers and the credential claiming overview for details. Use the quickstart to get started.

In-person (proximity) presentation

Your app presents credentials to nearby verifiers over Bluetooth Low Energy, following ISO/IEC 18013-5.

What you implement:

• Display a QR code for the verifier to scan (engagement phase).
• Handle the BLE connection and data exchange (managed by SDK).
• Show the user what data is being requested and collect consent.
• Display presentation result.

Key decisions:

• How to integrate the presentation trigger into your app's UI.
• Consent screen design (what data elements to show, how to explain them).
• How to handle offline scenarios (no network connectivity).
• Whether to prepare for NFC engagement (currently in development). For iOS apps, consider applying for the Apple NFC entitlement early to enable NFC-based engagement when available.

See the proximity presentation overview and tutorial.

Remote presentation

Your app responds to remote verification requests from web or mobile verifiers using ISO/IEC 18013-7 and OID4VP.

What you implement:

• Handle incoming presentation requests (redirect, QR, or Digital Credentials API).
• Show the user what data is being requested and collect consent.
• Submit the presentation response via the SDK.
• Handle same-device and cross-device scenarios.

Key decisions:

• Which invocation methods to support (redirects, QR scanning, Digital Credentials API).
• Same-device vs cross-device flow handling.
• How to return the user to the requesting app/website after presentation.

See the remote presentation overview and tutorial.

Integration architecture

The typical integration involves your existing mobile app, the MATTR Pi Holder SDK, and MATTR VII as the backend platform.

Components

Data flow

1. Claiming: Your app receives an offer URI → passes it to the SDK → SDK communicates with MATTR VII → credential is stored locally.
2. Proximity presentation: Verifier scans your app's QR → BLE session established → SDK handles exchange → user consents → data shared.
3. Remote presentation: Verifier sends request → your app receives it → SDK processes and validates → user consents → response sent.

Trust and security considerations

Trusted verifier management

The Holder SDK supports configurable trust lists for verifier certificates. You can adapt your app's behavior based on trust level:

• Block requests from untrusted verifiers entirely.
• Show warnings or reduced information for unrecognized verifiers.
• For remote presentations, verifier authentication is mandatory—the SDK validates the verifier's identity before proceeding.

Trusted issuer management

The SDK maintains a local list of trusted issuer certificates. Only credentials from issuers whose signing certificates are in your trust list will pass validation. Configure this list based on the jurisdictions and credential types your app supports.

Holder authentication

The SDK leverages platform-level security to ensure credentials are only presented by their rightful holder:

• Biometric authentication — require Face ID, Touch ID, or fingerprint before credential access.
• Device unlock — ensure the device has a passcode/PIN set.
• Key binding — credential keys are bound to the device's secure element or keystore.
• Per-credential policies — issuers can define security policies per credential type.

Balance security with inclusion: some users may lack or have disabled biometrics. The SDK supports OS-level alternatives (PIN, passcode, pattern) as fallbacks.

See the Device Key Authentication guide for detailed configuration.

Status list management

Credentials can be revoked after issuance. The SDK handles status list retrieval and caching based on the issuer's configured ttl and exp parameters:

• ttl — recommended duration for using a cached status list before fetching an update.
• exp — hard deadline after which a cached status list must not be used.

Apps can rely on cached statuses between ttl and exp to maintain offline usability. Consider how your app communicates credential status changes to the user (e.g., badge indicators, notifications).

See credential revocation for background on status lists.

Operational tooling

Activity log

The SDK provides an activity log that records credential lifecycle events (claimed, presented, declined, removed). Use this to build user-facing history views in your app.

SDK logging

For development and debugging, the SDK exposes diagnostic logging with configurable levels and callback hooks. Route SDK logs to your existing app telemetry or crash reporting tools.

Frequently asked questions

Can I add credential holding to my existing app without rebuilding it?

Yes. The MATTR Pi Holder SDK is designed to be added to existing mobile applications. You integrate it as a native dependency (CocoaPods/SPM for iOS, Maven/Gradle for Android, npm for React Native) and call SDK methods from your existing codebase.

What's the difference between MATTR Pi Holder SDK and MATTR GO Hold?

The MATTR Pi Holder SDK is a library you embed in your own app — you control the full user experience. MATTR GO Hold is a standalone wallet application ready for end users. Choose the SDK for custom integration; choose GO Hold for rapid deployment or pilots.

Does the SDK work offline?

Yes, for proximity presentation. The SDK uses BLE for in-person credential exchange and can verify credentials against locally cached trusted issuer certificates and status lists. Credential claiming and remote presentation require network connectivity.

Which credential formats are supported?

The MATTR Pi Holder SDK supports mDocs (aligned with ISO/IEC 18013-5) for both claiming and presentation. This includes mobile driver's licenses (mDLs) and other mDoc-based credentials.

How are credentials stored securely?

The SDK uses platform-native secure storage — iOS Keychain and Android Keystore. Credential keys are hardware-backed where available and bound to the device. Credentials cannot be extracted or cloned to another device.

Can my app claim credentials from any issuer?

Your app can claim credentials from any issuer using the OID4VCI standard. For verification of issuer trust, configure your trusted issuer certificate list to include the IACA certificates of issuers you accept.

How do I handle credential revocation in my app?

The SDK automatically checks status lists based on the issuer's ttl and exp configuration. Your app should handle the case where a previously valid credential's status changes — surface this to the user and, if appropriate, prompt them to obtain a replacement.

Can users present credentials to verifiers not using MATTR?

Yes. Because the SDK implements ISO/IEC 18013-5 (proximity) and ISO/IEC 18013-7 + OID4VP (remote), your app can present credentials to any standards-compliant verifier regardless of their platform provider.

What happens if the user switches devices?

Credentials are bound to the device's secure storage and cannot be transferred. Users will need to re-claim their credentials on a new device through the original issuer's offer flow.

How long does SDK integration typically take?

Basic credential claiming can be integrated in days. A full implementation covering claiming, proximity presentation, and remote presentation with polished UX typically takes 2–4 weeks for an experienced mobile team. The quickstart guide gets you to a first working integration quickly.