SDK Tethering

SDK Tethering ties each SDK/app instance to a MATTR VII tenant. Tethering establishes a trust relationship between your mobile application and the MATTR VII tenant, enabling the following capabilities:

• Operational insights: View details about registered and active app instances directly from your tenant.
• Licensing: On first initialization, the SDK registers the app instance with your tenant and obtains a license. The majority of the SDK's APIs require a valid license to operate.
• Remote management channel: SDK Tethering establishes a channel that we expect to extend in the future with capabilities such as remote syncing of trusted issuer lists and eventing.

SDK Tethering is available from the following SDK versions:

• iOS Verifier SDK: 6.0.0
• Android Verifier SDK: 7.0.0

How it works

The tethering process involves three steps:

1. Configure a Verifier Application on your MATTR VII tenant: You register your mobile app by creating a Verifier Application, identified by the bundle identifier (iOS) or the package fingerprint (Android).
2. Initialize the SDK with your tenant details: When you initialize the SDK in your app, you pass the details of the MATTR VII tenant and the Verifier Application you configured on it.
3. Automatic communication: Once initialized, instances of your app will automatically communicate with the configured MATTR VII tenant and retrieve the required tokens to operate and make requests to the tenant when required.

Token validity and offline use

The tokens issued during this process have configurable validity periods controlled by the maxTimeOfflineInSecs field on your Verifier Application configuration. This means your app can function without internet connectivity to meet different use cases:

• Minimum: 1 day (86400 seconds)
• Maximum: 30 days (2592000 seconds)
• Default: 7 days (604800 seconds)

When the license token expires, the SDK must reconnect to the MATTR VII tenant to renew it. Network access is required when registration or renewal is performed.

Configuring SDK Tethering

POST /v2/presentations/applications

{
    "name": "My iOS Verifier Application",
    "type": "ios",
    "bundleId": "com.yourcompany.verifierapp",
    "teamId": "YOUR_APPLE_TEAM_ID",
    "maxTimeOfflineInSecs": 864000,
    "appAttest": {
        "required": true,
        "environment": "production"
    }
}

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

POST /v2/presentations/applications

{
    "name": "My Android Verifier Application",
    "type": "android",
    "packageName": "com.yourcompany.verifierapp",
    "packageSigningCertificateThumbprints": [
        "1232584B6F6A892D356899FB9576C5F226A179E6199F2B7A1D837B5C234C5A8E"
    ],
    "maxTimeOfflineInSecs": 864000,
    "keyAttestation": {
        "required": true
    }
}

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

import { Platform } from "react-native";

const verifierApplicationId =
  Platform.OS === "ios"
    ? "YOUR_IOS_VERIFIER_APPLICATION_ID"
    : "YOUR_ANDROID_VERIFIER_APPLICATION_ID";

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
)

val platformConfig = PlatformConfiguration(
    tenantHost = URL("https://your-tenant.vii.mattr.global"),
    applicationId = "1ef1f867-20b4-48ea-aec1-bea7aff4964c"
)
MobileCredentialVerifier.initialize(context, platformConfig)

import { initialize } from "@mattrglobal/mobile-credential-verifier-react-native";

const result = await initialize();

if (result.isErr()) {
    console.error("Failed to initialize SDK:", result.error);
}

const result = await initialize({
    platformConfiguration: {
        tenantHost: "https://your-tenant.vii.mattr.global",
    },
});

if (result.isErr()) {
    console.error("Failed to initialize SDK:", result.error);
}

Once your Verifier Application configurations are created, your application will be able to use the SDK and interact with the MATTR VII platform (for example, to verify credential presentations).

Managing application instances

Once your Verifier Application is configured and the SDK is initialized, each device that launches your app registers as a new application instance on your tethered MATTR VII tenant. You can view and manage these instances via the MATTR VII API.

Retrieve all registered instances

To view all registered instances for a Verifier Application and track usage:

GET /v2/presentations/applications/{applicationId}/instances

• applicationId : The id of the Verifier Application you want to inspect.

The response includes a paginated list of all registered instances:

{
  "data": [
    {
      "id": "1ef1f867-20b4-48ea-aec1-bea7aff4964c",
      "appAttestationType": "app_attestation",
      "registeredAt": "2023-10-05T14:48:00.000Z",
      "licenseExpiresAt": "2024-10-05T14:48:00.000Z",
      "lastAttestedAt": "2023-12-01T10:30:00.000Z",
      "externalReferenceId": "external-ref-12345",
      "deviceDetails": {
        "deviceModel": "iPhone 12",
        "deviceMake": "Apple",
        "osVersion": "iOS 14.4"
      },
      "sdkDetails": {
        "sdkVersion": "1.2.3"
      }
    }
  ],
  "nextCursor": "Y3JlYXRlZEF0PTIwMjAtMDgtMjVUMDY6NDY6MDkuNTEwWiZpZD1hNjZmZmVhNS04NDhlLTQzOWQtODBhNC1kZGE1NWY1M2UzNmM"
}

Each instance includes:

• id : Unique identifier for the registered instance.
• appAttestationType : The type of attestation used during registration (none, app_attestation, or key_attestation).
• registeredAt : When the instance was first registered.
• licenseExpiresAt : When the instance's license expires (the Verifier SDK will automatically handle license renewal).
• lastAttestedAt : When the instance was last attested.
• deviceDetails : Information about the device (model, make, OS version).
• sdkDetails : Information about the SDK version used by the instance.

This is useful for tracking how many devices are actively using your application and monitoring usage quotas.

Delete a specific instance

To remove a specific registered instance:

DELETE /v2/presentations/applications/{applicationId}/instances/{instanceId}

• applicationId : The id of the Verifier Application.
• instanceId : The id of the specific instance to delete.

Once deleted, the instance can no longer interact with the platform or receive tokens, and any existing tokens are revoked.

Attestation vs Assertion fall-back

When configuring a Verifier Application, you control whether your MATTR VII tenant requires attestation (hardware-backed proof of app integrity) or also accepts a lighter-weight assertion (a cryptographic signature proving key possession) during instance registration and token renewal.

Each platform has an attestation configuration with a required boolean:

• When required is true, the app instance must provide a valid attestation during registration and token renewal.
• When required is false, your tenant also accepts an assertion when an attestation is not available.

The SDK handles this automatically. It always attempts to provide an attestation, and falls back to an assertion if it cannot generate one (for example, when the platform attestation service is temporarily unavailable). Your tenant then accepts or rejects the request based on the required setting. Your application does not need to manage attestation or assertion details directly.

When to use each setting