Getting started with the Verifier SDKs

Set up access to the MATTR Pi mDocs Verifier SDKs, configure SDK tethering, and initialize the SDK in your mobile application.

This guide walks you through the steps required to start building with the MATTR Pi mDocs Verifier SDKs. By the end, your mobile application will be ready to verify credential presentations. For the native iOS and Android Verifier SDKs, this includes tethering your application to a MATTR VII tenant. The React Native Verifier SDK is not tethered: for in-person (proximity) verification it does not require a MATTR VII tenant or platform configuration, and only needs a tenant for remote mobile (app-to-app) verification. React Native differences are called out at each step below.

Request SDK access

To access the MATTR Pi mDocs Verifier 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.

Create a MATTR VII tenant

The native iOS and Android Verifier SDKs require a MATTR VII tenant that serves as the backend for SDK operations including tethering and credential verification. For React Native, a tenant is only required for remote mobile (app-to-app) verification.

If you are building React Native for in-person verification only, you can skip this step.

Log into the MATTR Portal.
Select the Create/switch tenant button on the top-right side of the screen.
The All tenants panel is displayed, listing any existing tenants.
Select the Create new button.
The New tenant form is displayed.
Use the Region dropdown list to select the region your tenant will be hosted in.
Use the Tenant subdomain text box to insert a subdomain for your tenant (e.g. in-person-verification).
Select the Create button to create the new tenant.
Copy the displayed tenant information (audience, auth_url, tenant_url, client_id and client_secret).

Create a Verifier Application

The iOS and Android Verifier SDKs are tethered to a MATTR VII tenant. On initialization, the SDK registers your app instance with the tenant and obtains a license, so SDK Tethering must be configured before you initialize the SDK. For a full explanation of tethering and the capabilities it enables, see SDK Tethering.

To tether the SDK, create a Verifier Application on your MATTR VII tenant for the platform you are building.

While a Verifier Application can be created in the MATTR Portal, the settings that govern SDK Tethering are only available via the MATTR VII API. Any creation or update of a Verifier Application that supports SDK Tethering must therefore be performed using the API. Portal support will be added in the near future.

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

Request

POST /v2/presentations/applications

Request body

{
    "name": "My iOS Verifier Application",
    "type": "ios",
    "bundleId": "com.yourcompany.verifierapp",
    "teamId": "YOUR_APPLE_TEAM_ID",
    "appAttest": {
        "required": false,
        "environment": "development"
    }
}

name: A unique name to identify this Verifier 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 (must match the Team ID used to sign your app).
appAttest: App Attest configuration for the iOS verifier 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 Verifier Application:

Response

{
    "id": "1ef1f867-20b4-48ea-aec1-bea7aff4964c", 
    "name": "My iOS Verifier Application",
    "type": "ios",
    "bundleId": "com.yourcompany.verifierapp",
    "teamId": "YOUR_APPLE_TEAM_ID",
    "appAttest": {
        "required": false,
        "environment": "development"
    }
}

id: A unique identifier for the Verifier Application (generated by the tenant). You must use this value when initializing the SDK so that it can correctly identify and authenticate your application.

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

Request

POST /v2/presentations/applications

Request body

{
    "name": "My Android Verifier Application",
    "type": "android",
    "packageName": "com.yourcompany.verifierapp",
    "packageSigningCertificateThumbprints": [
        "1232584B6F6A892D356899FB9576C5F226A179E6199F2B7A1D837B5C234C5A8E"
    ],
    "keyAttestation": {
        "required": false
    },
    "openid4vpConfiguration": {
        "redirectUri": "com.yourcompany.verifierapp://oid4vp-callback"
    }
}

name: A unique name to identify this Verifier Application.
type: Must be android.
packageName: The package name of your Android application.
packageSigningCertificateThumbprints: SHA-256 hex-encoded fingerprints of the signing key certificates used to sign your APK or app bundle. This ensures the tenant only accepts requests from known and trusted applications. Refer to Android app signing for more information.
keyAttestation: Key Attestation configuration for the Android verifier application:
- required: When true, the app instance must provide a valid Key Attestation during registration and token renewal. When false, the app can register and renew tokens using just an authentication assertion. See Attestation vs Assertion for more details.
openid4vpConfiguration.redirectUri: Required by the create-application endpoint, which needs at least one of openid4vpConfiguration or dcApiConfiguration. In-person proximity verification does not use this redirect, so any valid custom-scheme URI is accepted here.

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

Response

{
    "id": "a82bfa46-72a0-4cde-b6cb-2a0de7e2f3c4", 
    "name": "My Android Verifier Application",
    "type": "android",
    "packageName": "com.yourcompany.verifierapp",
    "packageSigningCertificateThumbprints": [
        "1232584B6F6A892D356899FB9576C5F226A179E6199F2B7A1D837B5C234C5A8E"
    ],
    "keyAttestation": {
        "required": false
    }
}

id: A unique identifier for the Verifier Application (generated by the tenant). You must use this value when initializing the SDK so that it can correctly identify and authenticate your application.

SDK Tethering is currently not available in the React Native Verifier SDK.

Initialize the SDK

When you initialize the SDK, you must provide a PlatformConfiguration object with your tenant host and the id of the Verifier Application you created. This allows the SDK to register the app instance with your tenant and obtain a license to operate.

Initialize the SDK with your platform configuration. The initialize method is asynchronous, so call it from an asynchronous context:

Initialization

let platformConfig = PlatformConfiguration(
    tenantHost: URL(string: "https://your-tenant.vii.mattr.global")!,
    applicationId: "1ef1f867-20b4-48ea-aec1-bea7aff4964c"
)
try await MobileCredentialVerifier.shared.initialize(
    platformConfiguration: platformConfig
)

tenantHost: The URL of your MATTR VII tenant. This must be the tenant where your iOS Verifier Application is configured.
applicationId: The id of your configured iOS Verifier Application.

Initialize the SDK with your platform configuration: