Getting started with the Holder SDKs
Set up access to the MATTR Pi mDocs Holder SDKs, configure the SDK Backend, and initialize the SDK in your mobile application.
This guide walks you through the steps required to start building with the MATTR Pi mDocs Holder SDKs. By the end, your mobile application will be connected to a MATTR VII tenant and ready to use SDK capabilities such as credential claiming and presentation.
Request SDK access
To access the MATTR Pi mDocs Holder SDKs, complete the Get Started form with the following details:
- Your organization name and contact information.
- The platform(s) you plan to build for (iOS, Android, or React Native).
- A brief description of your use case.
Once your request is reviewed, you will receive access to the relevant SDK packages and the MATTR Portal.
Install the SDK
Add the SDK to your project and complete the platform specific setup. Check the Versions table for the current release of your platform, and System requirements for the toolchain each one needs.
Access to the iOS SDK is over git with SSH authentication, using an SSH key that belongs to a GitHub user with access to the distribution repository. If that setup gives you trouble, contact MATTR support.
Swift Package Manager
- In your project's Package Dependencies, select the
+icon to add a new package. - Paste
git@github.com:mattrsdk/ios-mobile-credential-holder-sdk.gitinto the search field. - Choose
ios-mobile-credential-holderfrom the search results. - Select Add Package.
CocoaPods
Add the source to the top of your Podfile, then add the pod to your target:
source 'git@github.com:mattrsdk/ios-mobile-credential-holder-sdk.git'
pod 'MobileCredentialHolderSDK', '~> 6.1.2'Then import the SDK where you use it:
import MobileCredentialHolderSDKInfo.plist
Proximity presentation uses Bluetooth, so your app must declare
NSBluetoothAlwaysUsageDescription. Without it the SDK can crash at runtime when it requests the
permission. The SDK makes the request itself, which may show the operating system's permission
prompt.
To keep a Bluetooth session alive while your app is in the background, also add to
UIBackgroundModes:
bluetooth-central, if you selectmDocClientCentralforbleMode.bluetooth-peripheral, if you selectmDocPeripheralServerforbleMode.
Entitlements
Add these only for the features you use:
- Associated Domains,
webcredentials:your.domain, for credential claiming. - App Attest,
com.apple.developer.devicecheck.appattest-environment, if you configure the SDK Backend. - Digital Credentials API, Mobile Document Provider, if you enable the
DC API. The document types in your entitlement must match the
ones you pass to
DCConfiguration.
Create a MATTR VII tenant
Your application requires a MATTR VII tenant. The tenant powers SDK operations including the SDK Backend, credential issuance, and verification.
- Log into the MATTR Portal.
- Create a new tenant to serve as the backend for your application.
- Note the tenant URL (e.g.,
https://your-tenant.vii.mattr.global) — you will need it when initializing the SDK.
Create a Holder Application
An SDK Backend is optional, but we recommend configuring it so your application can use capabilities such as Wallet Attestation and so you can view registered app instances from your tenant. To enable it, create a Holder Application on your MATTR VII tenant for each platform target.
For more details on the SDK Backend and the capabilities it enables, see SDK Backend.
The SDK Backend is optional. To configure it, create a Holder Application on your MATTR VII tenant for each platform target. A native iOS or Android app needs one, and a React Native app needs two, one per platform it targets. This is a one-time setup process that registers your app with the tenant and allows app instances to obtain the necessary tokens for authentication and operation.
You can create a Holder Application either in the MATTR Portal or via the MATTR VII API.
- Log in to the MATTR Portal and expand the Credential holding section in the left-hand navigation panel.
- Select Applications, then select the Create new button.
- Use the Name text box to insert a meaningful and friendly name for your application.
- Use the Client ID text box to insert the OAuth 2.0
client_idvalue that your holder application uses when requesting client attestations. This value must match theclient_idconfigured by issuers who trust this Holder Application. For more detail, see agreeing on a client identifier. - Use the Type radio button to select iOS.
- Use the Team ID text box to insert your Apple Developer Team ID.
- Use the Bundle ID text box to insert the Bundle ID of your app (must match your Xcode project configuration).
- Use the Max time offline field to set the maximum time the SDK can operate offline before requiring a new license token from the configured MATTR VII backend. The minimum is 1 day and the maximum is 30 days. The default is 7 days. Refer to token validity and offline use for more information.
- Select the App Attest checkbox to configure App Attest for this application. If you leave it
unselected, your tenant does not require an attestation but still validates any attestation it
receives against the
productionenvironment, so a build you run from Xcode on a physical device is rejected. Refer to App Attest environment mismatch (iOS) for more information. - Use the App Attest radio button to select Active or Inactive. When active, the app instance must provide a valid App Attest attestation during registration and token renewal. When inactive, an app instance that cannot produce an attestation can register and renew tokens with an authentication assertion instead. Refer to attestation vs assertion fall back for more information.
- Use the App Attest environment radio button to select Development or Production. This must match the environment your build attests against. Select Inactive with Development to accept both builds you run from Xcode on a physical device and iOS Simulator instances.
- Select the Create button to create the application and display its detail screen.
- Copy and record the
IDvalue. You will use it later when initializing the SDK so that it can correctly identify and authenticate your application.
Initialize the SDK
If you are using the SDK Backend, update your SDK initialization to include the platform
configuration once your Holder Applications are created. This enables your app to connect to the
correct MATTR VII tenant and Holder Application. If you are not using an SDK Backend, you can initialize
the SDK without a platformConfiguration.
A platform configuration also accepts an optional externalReferenceId, a developer-defined
identifier used to correlate this app instance with a record in MATTR VII. Set it if you want to
match registered app instances against your own records.
Initialize the SDK with your platform configuration:
let platformConfig = PlatformConfiguration(
tenantHost: URL(string: "https://your-tenant.vii.mattr.global")!,
applicationId: "1ef1f867-20b4-48ea-aec1-bea7aff4964c"
)
try await MobileCredentialHolder.shared.initialize(
platformConfiguration: platformConfig
)tenantHost: The URL of your MATTR VII tenant. This must be the tenant where your iOS Holder Application is configured.applicationId: Theidof your configured iOS Holder Application.
Next steps
Your application is now initialized and ready to use the SDK. If you configured a
platformConfiguration, it is also connected to your backend MATTR VII tenant. Explore the following guides
to start building:
- Credential claiming tutorial: Claim a verifiable credential into your holder app.
- Remote presentation tutorial: Present credentials to a web-based verifier.
- Proximity presentation tutorial: Present credentials in-person using Bluetooth.
- SDK Quickstart: Run a sample holder app end-to-end in 15-20 minutes.
- Handle SDK errors: Which failures the SDK expects you to handle, and which mean something has gone wrong.
How would you rate this page?
Last updated on