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.
• Wallet Attestation: Enable issuers to verify wallet integrity before issuing credentials. See Wallet Attestation for more information.
• 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 Holder SDK: 6.0.0
• Android Holder SDK: 7.0.0
• React Native Holder SDK: 10.0.0

How it works

The tethering process involves three steps:

1. Configure a Holder Application on your MATTR VII tenant: You register your mobile app by creating a Holder 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 Holder 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 Holder 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.

Configuring SDK Tethering

POST /v1/holder/applications

{
    "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": "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"
    }
}

POST /v1/holder/applications

{
    "name": "My Android Holder Application",
    "clientId": "my-wallet-client",
    "type": "android",
    "packageName": "com.yourcompany.holderapp",
    "packageSigningCertificateThumbprints": [
        "1232584B6F6A892D356899FB9576C5F226A179E6199F2B7A1D837B5C234C5A8E"
    ],
    "maxTimeOfflineInSecs": 864000,
    "keyAttestation": {
        "required": true
    }
}

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

import { Platform } from "react-native";

const holderApplicationId =
  Platform.OS === "ios"
    ? "YOUR_IOS_HOLDER_APPLICATION_ID"
    : "YOUR_ANDROID_HOLDER_APPLICATION_ID";

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
)

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

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

const applicationId =
    Platform.OS === "android"
        ? "your-android-holder-application-id"
        : "your-ios-holder-application-id";

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

Once your Holder Application configurations are created, your application will be able to use the SDK and interact with the MATTR VII platform (for example, to obtain attestation tokens).

Managing application instances

Once your Holder 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 Holder Application and track usage:

GET /v1/holder/applications/{applicationId}/instances

• applicationId : The id of the Holder 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 Holder 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 /v1/holder/applications/{applicationId}/instances/{instanceId}

• applicationId : The id of the Holder 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 Holder 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

Certificate expiry and required Key Attestation (Android)

This behavior is specific to Android Key Attestation. It does not apply to iOS App Attest.

When Key Attestation is set to required, an attestation must be present, parseable, and trusted (a trusted root with each certificate in the chain signed by the one above it) for registration to succeed.

One thing to be aware of: our validation does not check whether the certificates in the attestation chain have expired. Some Android devices, including relatively recent models, generate attestations where part or all of the certificate chain is already past its validity period. To avoid blocking these devices, an otherwise valid attestation with expired certificates is still treated as a successful attestation, even when Key Attestation is set to required.

In practice this means a device presenting an expired (but otherwise valid) attestation chain will register successfully and be marked as attested. This behavior may be tightened in a future release, so we recommend not relying on certificate expiry as part of your own trust decision.