React Native Holder SDK v10.0.0 Migration Guide

(Optional) Create Holder Applications on your MATTR VII tenant

The SDK Backend is optional in this release. If you do not need it, you can skip this step and the next one. The SDK continues to function without a platformConfiguration.

To configure the SDK Backend, the React Native Holder SDK connects to a MATTR VII tenant via the underlying native SDKs. This connection gives you access to a centralized view of registered and active app instances in MATTR VII, the optional Wallet Attestation feature, and other centralized management capabilities we plan to deliver over this channel.

Since React Native targets both iOS and Android, you need to create two Holder Applications, one for each platform target. A Holder Application is bound to platform-specific identifiers, so a single application cannot cover both targets. Use the same Client ID for both, so issuers see one wallet identity regardless of the platform your app runs on.

Create the iOS Holder Application

1. Log in to the MATTR Portal and expand the Credential holding section in the left-hand navigation panel.
2. Select Applications, then select the Create new button.
3. Use the Name text box to insert a meaningful and friendly name for your application, for example My RN Holder Application (iOS).
4. Use the Client ID text box to insert the OAuth 2.0 client_id that identifies your wallet application. This value is included in attestation JWTs and must match the client_id configured on the issuer's Authorization Server. Refer to agreeing on a client identifier for more information.
5. Use the Type radio button to select iOS.
6. Use the Team ID field to insert your Apple Developer Team ID.
7. Use the Bundle ID field to insert the Bundle ID of your iOS app (must match your Xcode project configuration).
8. Use the App Attest toggle to set whether App Attest is Active or Inactive, and, when active, use the App Attest environment toggle to select Development or Production. When active, the app instance must provide a valid App Attest attestation during registration and token renewal. When inactive, the app can register and renew tokens using an authentication assertion only. Refer to attestation vs assertion fall back for more information.
9. Use the Max time offline field to set the maximum time the SDK can operate offline before requiring a new license token. 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.
10. Select the Create button to create the application and display its detail screen.
11. Copy and record the ID value. You use it as the applicationId for the iOS target when initializing the SDK.

Create the Android Holder Application

1. Return to Applications in the Credential holding section and select the Create new button again.
2. Use the Name text box to insert a meaningful and friendly name for your application, for example My RN Holder Application (Android).
3. Use the Client ID text box to insert the same OAuth 2.0 client_id you used for the iOS Holder Application.
4. Use the Type radio button to select Android.
5. Use the Package name field to insert the package name of your Android application.
6. Use the Signing certificate thumbprints field to insert the 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.
7. Use the Key Attestation toggle to set whether Key Attestation is Active or Inactive. When active, the app instance must provide a valid Key Attestation during registration and token renewal. When inactive, the app can register and renew tokens using an authentication assertion only. Refer to attestation vs assertion fall back for more information.
8. Use the Max time offline field to set the maximum time the SDK can operate offline before requiring a new license token. 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.
9. Select the Create button to create the application and display its detail screen.
10. Copy and record the ID value. You use it as the applicationId for the Android target when initializing the SDK.

Once both Holder Applications are created, your application is able to use the SDK Backend and interact with the MATTR VII platform, for example to obtain attestation tokens.

(Optional) Configure the SDK Backend at initialization

To configure the SDK Backend, pass a platformConfiguration through the JS/TS layer into the native SDKs when initializing. This option is optional. Omit it to initialize the SDK without an SDK Backend.

Since React Native bridges both iOS and Android, and each platform has its own Holder Application registered on your MATTR VII tenant (see the previous step), your initialization code must pass the correct platform-specific applicationId at runtime. Use Platform.OS to select the appropriate value:

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

- await initialize({ instanceId: "your-instance-id" });
+ const applicationId =
+   Platform.OS === "android"
+     ? "your-android-holder-application-id"
+     : "your-ios-holder-application-id";
+
+ await initialize({
+   instanceId: "your-instance-id",
+   platformConfiguration: {
+     tenantHost: "https://your-tenant.vii.mattr.global",
+     applicationId,
+   },
+ });

• tenantHost: The URL of your MATTR VII tenant. This must be the tenant where your Holder Applications are configured.
• applicationId: The id of the Holder Application that matches the current platform target.

Replace the placeholder values with the ID recorded when you created each Holder Application. In practice, you would typically store these values in a configuration file or environment variables. When platformConfiguration is omitted, the SDK skips registration and does not connect to a backend, and wallet attestation is not available.

Confirm that:

• The applicationId used on iOS corresponds to the Holder Application created with your app's Bundle ID and Team ID.
• The applicationId used on Android corresponds to the Holder Application created with your app's package name and signing certificate thumbprints.
• Environment-specific tenant URLs are correctly configured.

Handle new error codes

This release adds error codes across several enums, and adds a new enum. Adding these values is a breaking change for exhaustive switch statements over these types, regardless of whether you configure the SDK Backend.

MobileCredentialHolderErrorType

Eight error codes that were previously declared only as per-function string literals are now members of the enum: FailedToRetrieveCredentials, FailedToDiscoverCredentialOffer, FailedToCreateAuthorizationSession, RedirectUriNotFound, InvalidTransactionCode, WebAuthenticationFailed, UnsupportedDeviceKeyAuthenticationPolicy, and InvalidCredentialOffer. Their values are unchanged, and the per-function enums that reference them (DiscoverCredentialOfferErrorType, CreateAuthorizationSessionErrorType, and RetrieveCredentialsErrorTypes) keep the same values.

The following members are new:

• StorageInitialization: storage could not be initialized for the SDK.
• SdkNotInitialized: the SDK has not been initialized.
• DeviceKeyGenerationError: a device key could not be generated.
• DeviceKeyNotDeleted: a device key could not be deleted from storage.
• InvalidCertificate: a supplied certificate is not valid.
• ClientMetadataServiceError: verifier client metadata could not be resolved during an online presentation.
• ResponseModeNotSupported: the authorization request asked for an unsupported response mode.
• FailedToCreateProximityPresentationSession: a proximity presentation session could not be created.
• NfcDeviceEngagementNotFound: a proximity session was started with engagementFromNfc but no NFC device engagement was available.
• ActivityRequired: an Android activity is required to complete the operation.
• InvalidDeviceKeyAuthenticationPolicy: the supplied device key authentication policy is not valid.
• DeviceKeyAuthenticationPolicyChangedException: the authentication policy of an existing device key has changed.
• UserAuthenticationInvalidatedByBiometricEnrollment: the device key was invalidated because the biometrics enrolled on the device changed.
• UserAuthenticationNotSupported: the requested user authentication configuration is not supported on this device.
• MACAuthenticationUnavailableForAuthenticationPolicy: MAC authentication cannot be used with the credential's authentication policy.
• CalledFromAppExtension: an API that is unavailable in app extensions was called from an iOS app extension.
• OperationFailed: the operation failed for a platform-specific reason described in the error message.
• RuntimeException: an unexpected or unrecoverable failure in the SDK.

ProximityPresentationSessionErrorType

• ResponseNotCreated: the response to send to the verifier could not be created.
• ResponseEncryptionFailed: the response could not be encrypted.
• SessionDecryption: the device request could not be decrypted.
• PresentationNotCreated: the credential presentation could not be created.

MobileCredentialHolderReactNativeErrorType (new)

This new enum holds the error codes raised by the React Native SDK itself, rather than reported by the device platform:

• InvalidParams: the arguments passed to a function are missing or invalid. This code is thrown rather than returned in a Result, so read it from the code field of the caught error. See Keep argument objects to documented fields.
• ExistingProximityPresentationSessionNotFound: there is no active proximity presentation session. This code moved here from MobileCredentialHolderErrorType.

SDK Backend errors

initialize may now return two errors related to the SDK Backend:

• InvalidLicense: the SDK license failed to validate or has expired.
• FailedToRegister: registering the app instance with MATTR VII failed.

InvalidLicense may also be returned by most public APIs when an SDK Backend is configured but a valid license is not present. This includes addCredential, getCredential, getCredentials, deleteCredential, generateDeviceKey, discoverCredentialOffer, createAuthorizationSession, retrieveCredentials, retrieveCredentialsUsingAuthorizationSession, createOnlinePresentationSession, createProximityPresentationSession, sendProximityPresentationResponse, getCurrentProximityPresentationSession, addTrustedIssuerCertificates, getTrustedIssuerCertificates, deleteTrustedIssuerCertificate, addTrustedVerifierCertificates, getTrustedVerifierCertificates, and deleteTrustedVerifierCertificate.

Wallet Attestation errors

retrieveCredentials and retrieveCredentialsUsingAuthorizationSession may now return two errors related to Wallet Attestation:

• InvalidCredentialOffer: the offer requires attestation but no platformConfiguration was provided, or the SDK supports none of the authorization server's advertised client authentication methods.
• InvalidWalletAttestation: the authorization server rejected the attestation token.

When attestation fails for an individual credential, that credential's RetrieveCredentialFailure carries an invalidWalletAttestation error. Wallet attestation errors only occur when an SDK Backend is configured and an issuer requires attestation.

RuntimeException may be thrown by any function

RuntimeException is the catch-all for an unexpected or unrecoverable failure in the SDK. Because any function may throw it, it is not listed in each function's expected Result error type. Handle it with your generic fallback strategy and report it to MATTR.

Update your error handling, logging, analytics, and support diagnostics to account for these new error codes.

Update client_id configuration

Previously, the client_id passed to retrieveCredentials was not shared with the issuer during the pre-authorized code flow, so any value would work. This is no longer the case. The SDK now presents the client_id to the issuer as part of wallet attestation, and the issuer validates it against its list of trusted wallet providers.

To prepare for this change:

1. Coordinate with the issuer to register your wallet application as a trusted wallet provider. The issuer will provide you with a client_id that identifies your application. Refer to agreeing on a client identifier for more information.
2. Pass the issuer-provided client_id in the options when calling retrieveCredentials.

  const result = await retrieveCredentials({
    credentialOffer: offer,
-   clientId: "any-value",
+   clientId: "issuer-provided-client-id",
  });

Issuance flows that previously worked with an arbitrary client_id will fail if the issuer requires a trusted wallet provider. Ensure you have coordinated with each issuer and obtained the correct client_id before upgrading. Test direct issuance flows to confirm credentials are issued successfully.

Handle the new Result returns

Seven functions that previously resolved a plain value now return a neverthrow Result, so their expected error cases surface as typed values you can handle. Callers must handle the Result instead of using the resolved value directly. These functions can still throw, so a try/catch is still required alongside handling the Result.

The matching error types are now exported from the package: DeleteCredentialError, DestroyError, DeleteTrustedVerifierCertificateError, GetCredentialsError, GetTrustedIssuerCertificatesError, GetTrustedVerifierCertificatesError, and GetCurrentProximityPresentationSessionError.

Update each call site to handle the Result:

- const credentials = await getCredentials();
+ try {
+   const getCredentialsResult = await getCredentials();
+
+   if (getCredentialsResult.isErr()) {
+     // Handle the error from getCredentialsResult.error
+     return;
+   }
+
+   const credentials = getCredentialsResult.value;
+ } catch (error) {
+   // Handle unexpected thrown errors
+ }

Refer to each function's @throws annotation for the errors it can throw, and to RuntimeException may be thrown by any function.

Functions that already returned a Result, such as initialize and retrieveCredentials, are unchanged. isInitialized and terminateProximityPresentationSession still resolve plain values and are also unchanged.

Update credential retrieval result handling

RetrieveCredentialsResponse has changed from an array of flat objects with optional fields to an array of RetrieveCredentialItem, a discriminated union with isSuccess as the discriminator. Each item is either a RetrieveCredentialSuccess (with isSuccess: true, docType, and credentialId) or a RetrieveCredentialFailure (with isSuccess: false, docType, and error). TypeScript enforces which fields are available after narrowing.

Update your result iteration logic to narrow on isSuccess:

  const result = await retrieveCredentials(options);

  if (result.isOk()) {
    for (const item of result.value) {
-     if (item.credentialId) {
-       // Use item.doctype and item.credentialId
-       console.log(item.credentialId);
+     if (item.isSuccess) {
+       // item is RetrieveCredentialSuccess, so credentialId is guaranteed
+       console.log(item.credentialId);
      } else {
-       // Use item.doctype and item.error
-       console.log(item.error?.message);
+       // item is RetrieveCredentialFailure, so error is guaranteed
+       console.log(item.error.message);
      }
    }
  }

• The error field is no longer optional. It is always present on failure items and never present on success items.
• The credentialId field is no longer optional. It is always present on success items and never present on failure items.

Update TypeScript type guards, tests, and any downstream logic that checked for optional fields.

Rename doctype to docType

The doctype field has been renamed to docType (camelCase) to align naming across iOS and Android. This affects credential retrieval result items and OfferedCredential returned by discoverCredentialOffer.

Update all references from .doctype to .docType:

- const documentType = credential.doctype;
+ const documentType = credential.docType;

Rename MobileCredentialAuthenticationOption to DeviceAuthenticationOption

MobileCredentialAuthenticationOption has been renamed to DeviceAuthenticationOption, aligning naming with the native Holder SDKs, which made the same rename in iOS 6.0.0 and Android 7.0.0. The Signature and Mac values are unchanged.

Update all imports and type references, and rename the mobileCredentialAuthenticationOption option on createProximityPresentationSession to deviceAuthenticationOption:

- import { MobileCredentialAuthenticationOption } from "@mattrglobal/mobile-credential-holder-react-native";
+ import { DeviceAuthenticationOption } from "@mattrglobal/mobile-credential-holder-react-native";

- const authOption: MobileCredentialAuthenticationOption = MobileCredentialAuthenticationOption.Mac;
+ const authOption: DeviceAuthenticationOption = DeviceAuthenticationOption.Mac;

  await createProximityPresentationSession({
    onRequestReceived,
-   mobileCredentialAuthenticationOption: authOption,
+   deviceAuthenticationOption: authOption,
  });

Neither previous name is exported any more. On Android, passing the old mobileCredentialAuthenticationOption key fails with an InvalidParams error rather than being ignored, as described in Keep argument objects to documented fields. On iOS the key is ignored and the default authentication option is used.

Migrate DeviceKeyAuthenticationType to UserAuthenticationType

The DeviceKeyAuthenticationType enum export has been removed. Use UserAuthenticationType instead, which now carries the same values:

• None
• UserPresence
• BiometryAny
• BiometryCurrentSet
• DeviceCredential

Update all references, including the type field of the DeviceKeyAuthenticationPolicy passed to generateDeviceKey, retrieveCredentials, and retrieveCredentialsUsingAuthorizationSession:

- import { DeviceKeyAuthenticationType } from "@mattrglobal/mobile-credential-holder-react-native";
+ import { UserAuthenticationType } from "@mattrglobal/mobile-credential-holder-react-native";

  const result = await generateDeviceKey({
    issuer,
    audience,
-   authenticationPolicy: { type: DeviceKeyAuthenticationType.BiometryCurrentSet },
+   authenticationPolicy: { type: UserAuthenticationType.BiometryCurrentSet },
  });

The DeprecatedDeviceKeyAuthenticationType enum, and its BiometricOnly and BiometricOrPasscode values, has also been removed. A device key that was previously associated with a deprecated type is now reported as its modern equivalent, so update any code that reads DeviceKeyAuthenticationInfo.type:

- case DeprecatedDeviceKeyAuthenticationType.BiometricOnly:
+ case UserAuthenticationType.BiometryCurrentSet:

- case DeprecatedDeviceKeyAuthenticationType.BiometricOrPasscode:
+ case UserAuthenticationType.UserPresence:

Update userAuthenticationType at initialization

UserAuthenticationType is also used for the userAuthenticationType field of the userAuthenticationConfiguration passed to initialize. It previously carried only BiometricOnly and BiometricOrPasscode. It now carries the same values used for device key authentication policies:

• None
• UserPresence, which replaces BiometricOrPasscode
• BiometryAny
• BiometryCurrentSet, which replaces BiometricOnly
• DeviceCredential

The default for userAuthenticationType is now UserPresence, previously BiometricOrPasscode.

  await initialize({
    userAuthenticationConfiguration: {
      userAuthenticationBehavior: UserAuthenticationBehavior.OnDeviceKeyAccess,
-     userAuthenticationType: UserAuthenticationType.BiometricOrPasscode,
+     userAuthenticationType: UserAuthenticationType.UserPresence,
    },
  });

userAuthenticationType is no longer iOS only, so review the effect of your configuration on Android as well. initialize may now return UserAuthenticationNotSupported on Android when BiometryCurrentSet is combined with a userAuthenticationBehavior of OnInitialize.

Update VerificationResult failure handling

On a failed verification, the failure detail has moved from a reason property to failureType, and the VerificationFailedReason type has been removed. The { type, message } value shape is unchanged.

  if (!credential.verificationResult.verified) {
-   console.log(credential.verificationResult.reason.type);
+   console.log(credential.verificationResult.failureType.type);
  }

Rename every .reason access on a VerificationResult to .failureType, and remove any use of VerificationFailedReason from your type annotations and downstream mapping logic.

Handle optional OfferedCredential.claims

claims on OfferedCredential (returned in credentials from discoverCredentialOffer) is now optional and is only present for offers that contain claim data. This aligns with the OID4VCI 1.0 specification.

Handle the case where claims is absent rather than assuming an array is always present:

- for (const claim of offeredCredential.claims) {
-   // Use the claim
- }
+ // claims may be undefined when the offer contains no claim data
+ for (const claim of offeredCredential.claims ?? []) {
+   // Use the claim
+ }

Handle credentials with empty claims

Retrieving or adding a credential whose issuer signed data contains no namespaces, or a namespace with no claims, now fails with a decoding error instead of producing a credential with empty claims.

This guarantees that MobileCredential.claims and MobileCredentialMetadata.claims are always populated, so you can remove defensive checks for empty claim data. Handle the error where credentials are retrieved or added, and check the per-credential error on any RetrieveCredentialFailure item.

Keep argument objects to documented fields

Invalid or malformed arguments are now rejected with an InvalidParams error code and a message describing the offending field, instead of a synchronous Error with a message of the form Invalid arguments for '<function>' function: .... Update any code that matched on the previous message:

  try {
    await addCredential(options);
  } catch (error) {
-   if (error.message.startsWith("Invalid arguments for 'addCredential' function")) {
+   if ((error as RCTBridgeError).code === "InvalidParams") {
      // Handle the invalid argument
    }
  }

Android also now rejects unrecognized keys in argument objects. Any extra or misspelled field that is not part of a function's documented options fails with an InvalidParams error. iOS ignores unknown keys. Ensure argument objects contain only documented fields so behavior is consistent across platforms:

  const credential = await getCredential(credentialId, {
    fetchUpdatedStatusList: false,
-   skipStatusCheck: true,
  });

Update renamed and removed exports

Update your imports and type references:

- import { SessionStatus, DateTime } from "@mattrglobal/mobile-credential-holder-react-native";
+ import { SessionStatusErrorType } from "@mattrglobal/mobile-credential-holder-react-native";

- const validFrom: DateTime = credential.validityInfo.validFrom;
+ const validFrom: Date = credential.validityInfo.validFrom;

RetrieveCredentialsErrorTypes.UserAuthenticationFailed now has the value "UserAuthentication", previously "UserAuthenticationFailed". Code that compares the enum member is unaffected. Code that compares the raw error string must be updated, and we recommend switching to the enum member:

  if (result.isErr()) {
-   if (result.error.type === "UserAuthenticationFailed") {
+   if (result.error.type === RetrieveCredentialsErrorTypes.UserAuthenticationFailed) {
      // Handle the failed user authentication
    }
  }

Two errors are no longer raised and have been removed from the error types they appeared in, so you can remove their handling:

• sendOnlinePresentationResponse no longer returns AuthorizationResponseJWECreationFailed.
• sendProximityPresentationResponse no longer returns UserAuthenticationUnrecoverableKey.