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. 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 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, 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.
-
When App Attest is active, use the App Attest environment toggle to select Development or Production. Apple recommends
developmentfor testing andproductionfor distribution builds.Inactive does not disable App Attest. Your tenant still validates any attestation an app instance sends, and with no configuration stored it expects the
productionenvironment. A build you run from Xcode on a physical device attests againstdevelopment, so it is rejected withThe attestation environment does not match the expected environment: production. To develop against physical devices, select Active and Development. See App Attest environment mismatch (iOS) for the full set of options. -
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
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.
How would you rate this page?
Last updated on