SDK Backend

Learn how MATTR Verifier SDKs connect to a backend MATTR VII tenant through Verifier Application configuration, giving you visibility over app instances and licensing.

An SDK Backend connects each app instance to a backend MATTR VII tenant. This builds on the secure connection your apps already make to your tenant, and gives you:

Visibility and usage insights: View details about registered and active app instances directly from your tenant, so you can measure adoption and report on usage.
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.
A foundation for flexible app management: The SDK Backend establishes a channel we expect to extend over time, for example keeping trusted issuer lists current and updating app settings without waiting for an app store release.

SDK Backend support is required from the following SDK versions:

iOS Verifier SDK: 6.0.0
Android Verifier SDK: 7.0.0

How it works

Setting up the SDK Backend involves three steps:

Configure a Verifier Application on your MATTR VII tenant: You register your mobile app by creating a Verifier Application, identified by the bundle identifier and team ID (iOS) or the package fingerprint (Android).
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.
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 the SDK Backend

Configure Verifier Applications

You can create and configure a Verifier Application, including the SDK Backend settings, either in the MATTR Portal or via the MATTR VII API.

Log in to the MATTR Portal and expand the Credential verification 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 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.

Set these fields in accordance with how you intend to use the app. For the specific values a given workflow expects, follow the relevant quickstart or tutorial for in-person or remote mobile verification.

Inactive does not disable App Attest. Your tenant still validates any attestation an app instance sends, and with no configuration stored it expects the production environment. A build you run from Xcode on a physical device attests against development, so it is rejected with The 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 Allowed presentation method radio button to select how the application verifies credentials:
- In-person only: the application only verifies credentials in person (proximity). The remote presentation configuration is hidden.
- Remote and in-person: the application verifies credentials both remotely and in person. Configure the OID4VP settings for the remote presentation flow by setting the OID4VP redirect URI the user is returned to after presenting a credential.
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 ID value. You must use it when initializing the SDK so that it can correctly identify and authenticate your application.

Initialize the SDK with platform configuration

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.

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 configured backend 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:

Request

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:

Response

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

Request

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.

Deleting instances is primarily useful during testing when you have a limited number of devices and need to re-register a fresh instance (for example, to test the initial registration flow again). In production, there is nothing preventing the application from requesting another token on the next launch, which would create a new instance — so deleting instances is not an effective way to block a device.

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

Scenario	Recommended setting
Production apps in distribution	`required: true`: Provides the strongest integrity guarantees by verifying the app and device through OS-level attestation.
Development and testing	`required: false`: Useful when running on simulators or devices where attestation services are unavailable. On iOS, also set `environment` to `development` so that builds you run from Xcode are accepted. See App Attest environment mismatch (iOS).
Broad device compatibility	`required: false`: Some older devices may not support hardware attestation. The assertion fall-back ensures these devices can still register.

Setting attestation to required: false reduces the security guarantees of the SDK Backend. Only use this setting when you have a specific need, such as supporting older devices or during development.

App Attest environment mismatch (iOS)

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

Apple issues every attestation against one of two environments, development or production. The environment is fixed in the app binary when you build it, and neither the SDK nor your tenant can change it at runtime. Your tenant compares the environment of the attestation it receives against the environment value on your Verifier Application, and rejects the request when the two differ:

Response

{
    "code": "InvalidAttestation",
    "message": "The attestation environment does not match the expected environment: production"
}

Two details make this error straightforward to run into:

required: false does not turn App Attest off. It only allows an app instance to register without an attestation. When an app instance does send an attestation, your tenant always validates it, including the environment check. The iOS Verifier SDK attempts App Attest on every physical device that supports it, so on a real device an attestation is nearly always sent.
Leaving appAttest out is the same as expecting production. When a Verifier Application has no appAttest configuration, your tenant expects the production environment by default.

Put together, this means a build you run from Xcode on a physical device attests against Apple's development environment, so it is rejected by a Verifier Application that expects production, even when App Attest is not required.

Match the configuration to your build. We recommend a separate Verifier Application per environment, so that a non-production configuration never has to accept production builds, or the other way around:

How you build and install the app	Environment Apple attests against	Verifier Application configuration
Run from Xcode on a physical device	`development`	`required: false` with `environment: development`
Run on the iOS Simulator	None. App Attest is unavailable, so the SDK sends an assertion instead	`required: false` with either `environment`
Distribute through TestFlight or the App Store	`production`	`required: true` with `environment: production`

Set the App Attest environment in Xcode. The environment comes from your app's com.apple.developer.devicecheck.appattest-environment entitlement:

YourApp.entitlements

<key>com.apple.developer.devicecheck.appattest-environment</key>
<string>development</string>

If you leave this key out, the environment follows how the app was provisioned and installed. Builds you run from Xcode against a development profile attest against development, and builds you distribute through TestFlight or the App Store attest against production. We recommend setting the key explicitly in each build configuration so that the behavior is predictable, and so that it is clear which Verifier Application the build is meant to register against.

Configuring this in the MATTR Portal. The Portal offers two states for App Attest, and neither of them sends required: false with environment: development:

Portal setting	Configuration sent to your tenant	Result on a physical device
Inactive	No `appAttest` configuration, so `production` is expected	A build run from Xcode is rejected
Active with Development	`required: true` with `environment: development`	A build run from Xcode is accepted. Simulator instances are rejected, because they cannot attest
Active with Production	`required: true` with `environment: production`	Only TestFlight and App Store builds are accepted

To develop against physical devices in the Portal, select Active and Development. Do not use Inactive for this, because it expects the production environment. If you also need Simulator instances to register against the same Verifier Application, create or update it through the API with required: false and environment: development, which accepts both.

An SDK Backend connects each app instance to a backend MATTR VII tenant. This builds on the secure connection your apps already make to your tenant, and gives you:

Visibility and usage insights: View details about registered and active app instances directly from your tenant, so you can measure adoption and report on usage.
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.
A foundation for flexible app management: The SDK Backend establishes a channel we expect to extend over time, for example keeping trusted issuer lists current and updating app settings without waiting for an app store release.

SDK Backend support is required from the following SDK versions:

iOS Verifier SDK: 6.0.0
Android Verifier SDK: 7.0.0

How it works

Setting up the SDK Backend involves three steps:

Configure a Verifier Application on your MATTR VII tenant: You register your mobile app by creating a Verifier Application, identified by the bundle identifier and team ID (iOS) or the package fingerprint (Android).
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.
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

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 the SDK Backend

Configure Verifier Applications

You can create and configure a Verifier Application, including the SDK Backend settings, either in the MATTR Portal or via the MATTR VII API.

Log in to the MATTR Portal and expand the Credential verification 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 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.

Set these fields in accordance with how you intend to use the app. For the specific values a given workflow expects, follow the relevant quickstart or tutorial for in-person or remote mobile verification.

Inactive does not disable App Attest. Your tenant still validates any attestation an app instance sends, and with no configuration stored it expects the production environment. A build you run from Xcode on a physical device attests against development, so it is rejected with The 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 Allowed presentation method radio button to select how the application verifies credentials:
- In-person only: the application only verifies credentials in person (proximity). The remote presentation configuration is hidden.
- Remote and in-person: the application verifies credentials both remotely and in person. Configure the OID4VP settings for the remote presentation flow by setting the OID4VP redirect URI the user is returned to after presenting a credential.
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 ID value. You must use it when initializing the SDK so that it can correctly identify and authenticate your application.

Initialize the SDK with platform configuration

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.

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

Retrieve all registered instances

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

Request

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:

Response

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

Request

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

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.

When to use each setting

Scenario	Recommended setting
Production apps in distribution	`required: true`: Provides the strongest integrity guarantees by verifying the app and device through OS-level attestation.
Development and testing	`required: false`: Useful when running on simulators or devices where attestation services are unavailable. On iOS, also set `environment` to `development` so that builds you run from Xcode are accepted. See App Attest environment mismatch (iOS).
Broad device compatibility	`required: false`: Some older devices may not support hardware attestation. The assertion fall-back ensures these devices can still register.

App Attest environment mismatch (iOS)

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

Response

{
    "code": "InvalidAttestation",
    "message": "The attestation environment does not match the expected environment: production"
}

Two details make this error straightforward to run into:

required: false does not turn App Attest off. It only allows an app instance to register without an attestation. When an app instance does send an attestation, your tenant always validates it, including the environment check. The iOS Verifier SDK attempts App Attest on every physical device that supports it, so on a real device an attestation is nearly always sent.
Leaving appAttest out is the same as expecting production. When a Verifier Application has no appAttest configuration, your tenant expects the production environment by default.

How you build and install the app	Environment Apple attests against	Verifier Application configuration
Run from Xcode on a physical device	`development`	`required: false` with `environment: development`
Run on the iOS Simulator	None. App Attest is unavailable, so the SDK sends an assertion instead	`required: false` with either `environment`
Distribute through TestFlight or the App Store	`production`	`required: true` with `environment: production`

Set the App Attest environment in Xcode. The environment comes from your app's com.apple.developer.devicecheck.appattest-environment entitlement:

YourApp.entitlements

<key>com.apple.developer.devicecheck.appattest-environment</key>
<string>development</string>

Configuring this in the MATTR Portal. The Portal offers two states for App Attest, and neither of them sends required: false with environment: development:

Portal setting	Configuration sent to your tenant	Result on a physical device
Inactive	No `appAttest` configuration, so `production` is expected	A build run from Xcode is rejected
Active with Development	`required: true` with `environment: development`	A build run from Xcode is accepted. Simulator instances are rejected, because they cannot attest
Active with Production	`required: true` with `environment: production`	Only TestFlight and App Store builds are accepted

How it works

Token validity and offline use

Configuring the SDK Backend

Configure Verifier Applications

Initialize the SDK with platform configuration

Managing application instances

Retrieve all registered instances

Delete a specific instance

Attestation vs Assertion fall-back

When to use each setting

App Attest environment mismatch (iOS)

On this page

SDK Backend

How it works

Token validity and offline use

Configuring the SDK Backend

Configure Verifier Applications

Initialize the SDK with platform configuration

Managing application instances

Retrieve all registered instances

Delete a specific instance

Attestation vs Assertion fall-back

When to use each setting

App Attest environment mismatch (iOS)

On this page