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.

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 (iOS and Android). 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_id value that your holder application uses when requesting client attestations. This value must match the client_id configured 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 App Attest toggle to set whether App Attest is Active or Inactive. When active, the app instance must provide a valid App Attest attestation during registration and token renewal. When inactive, the app can register and renew tokens using an authentication assertion only. Refer to attestation vs assertion fall back for more information.
When App Attest is active, use the App Attest environment toggle to select Development or Production. Apple recommends development for testing and production for distribution builds.
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 Create button to create the application and display its detail screen.
Copy and record the ID value. 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.

Initialize the SDK with your platform configuration:

Initialization

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: The id of 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.