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.

Creating a Holder Application is currently not available in the MATTR Portal and must be performed using the MATTR VII API. Portal support will be added in the near future.

Make a request of the following structure to create an iOS Holder Application configuration on your MATTR VII tenant:

Request

POST /v1/holder/applications

Request body

{
    "name": "My iOS Holder Application",
    "clientId": "my-wallet-client",
    "type": "ios",
    "bundleId": "com.yourcompany.holderapp",
    "teamId": "YOUR_APPLE_TEAM_ID",
    "maxTimeOfflineInSecs": 864000,
    "appAttest": {
        "required": true,
        "environment": "production"
    }
}

name: A unique name to identify this Holder Application.
clientId: OAuth 2.0 client_id value that the holder application uses when requesting client attestations. This value is included as the sub claim in attestation JWTs and must match the client_id configured by issuers who trust this Holder Application.
type: Must be ios.
bundleId: The Bundle ID of your iOS app (must match your Xcode project configuration).
teamId: Your Apple Developer Team ID.
maxTimeOfflineInSecs: Maximum number of seconds the SDK can operate offline before requiring a new license token. Must be between 1 day (86400) and 30 days (2592000). Defaults to 7 days (604800).
appAttest: App Attest configuration for the iOS holder application:
- required: When true, the app instance must provide a valid App Attest attestation during registration and token renewal. When false, the app can fall back to assertion-only authentication. See Attestation vs Assertion for more details.
- environment: The App Attest environment (development or production). Apple recommends using development for testing and production for distribution builds.

A successful response returns a 201 status code with the created Holder Application:

Response

{
    "id": "1ef1f867-20b4-48ea-aec1-bea7aff4964c", 
    "name": "My iOS Holder Application",
    "clientId": "my-wallet-client",
    "type": "ios",
    "bundleId": "com.yourcompany.holderapp",
    "teamId": "YOUR_APPLE_TEAM_ID",
    "maxTimeOfflineInSecs": 864000,
    "appAttest": {
        "required": true,
        "environment": "production"
    }
}

id: A unique identifier for the Holder Application (generated by the tenant). You must use this value 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.