Holder SDK quickstart guide

1. Download and unzip the sample iOS holder project.
2. Use Xcode to open the .xcodeproj file in the unzipped folder.
3. Drag the MobileCredentialHolderSDK-*version*.xcframework folder (obtained from MATTR as part of the SDK package) into your project.
4. Configure MobileCredentialHolderSDK-*version*.xcframework to Embed & sign.
5. Set a unique bundle identifier for the project in the Xcode project settings (e.g., com.yourname.holdersample).
6. Run the project on a physical iOS device (simulators do not support the required Bluetooth capabilities).

1. Download and unzip the sample Android holder project.
2. Open the project in Android Studio.
3. Unzip the mobile-credential-holder-*version*.zip file (obtained from MATTR as part of the SDK package).
4. Drag the unzipped global folder into the project's repo folder.
5. Sync Project with Gradle files to recognize the new module.
6. Run the project on a physical Android device (emulators do not support the required Bluetooth capabilities).

1. Access the sample holder codebase by either:

   • Cloning the MATTR Sample Apps repository:

     git clone https://github.com/mattrglobal/sample-apps.git

   • Or downloading just the holder sample using download-directory.github.io.

2. Open the completed sample holder project in your code editor. You can find it in the sample-apps/react-native-mdocs-holder-tutorial/react-native-mdocs-holder-tutorial-complete directory.

3. Open the app.config.ts file.

4. Update the iOS bundleIdentifier to a unique value for your application, e.g. com.mycompany.myapp.

5. Update the Android package to a unique value, e.g. com.mycompany.myapp.

6. Navigate to the project directory and install dependencies:

   yarn install

7. Run the following command to generate the iOS and Android project files:

   npx expo prebuild

   You should now see the ios and android folders in your project root.

8. Connect your testing device and run the following command to start the application:

   iOS

   yarn ios --device

   Android

   yarn android --device

1. Use a mobile browser on the device where the sample application is installed to navigate to the MATTR Labs remote presentation testing tool.
2. Select the OID4VP (Redirect) option from the Select Experience list.
3. Select Request credentials.
4. Select Allow to open the sample application.
5. Select the credential you claimed in the previous part.
6. Select Send Response.
7. You should be redirected back to the MATTR Labs remote presentation testing tool, where you will see a successful verification indication.

1. Use a desktop browser to navigate to the MATTR Labs remote presentation testing tool.
2. Select OID4VP (Redirect) from the Select Experience list.
3. Select Request credentials.
4. Open the camera on the device where the sample application is installed and scan the QR code.
5. Confirm opening the QR code with your sample application (this message might vary depending on your device and platform).
6. Select the credential you claimed in the previous part.
7. Select Send Response.
8. Back on your desktop browser, you should see a successful verification indication.

try mobileCredentialHolder.initialize(
    userAuthenticationConfiguration: UserAuthenticationConfiguration( 
        userAuthenticationBehavior: .always, 
        userAuthenticationType: .biometricOrPasscode, 
        presentationTimeoutSeconds: 20
    ),
    credentialIssuanceConfiguration: CredentialIssuanceConfiguration(
        redirectUri: "<WalletRedirectUri>", 
        autoTrustMobileCredentialIaca: true
    ),
    dcConfiguration: DCConfiguration( // iOS 26+ only
        appGroup: "group.com.yourcompany.app", 
        supportedDocTypes: [.mDL, .eudi] 
    ) 
)

• userAuthenticationConfiguration: Optional. Configures when the SDK requires user authentication to access or present credentials. The example shows the default values. Refer to the reference documentation for additional details about the available configuration options.
• redirectUri : Provide a URL that corresponds to a specific path in your application. The SDK will redirect the user to this path after they successfully complete authentication. Required for the Authorization Code flow.
• autoTrustMobileCredentialIaca : Set to true if you trust the credential issuer(s) for any offer. Defaults to false.
• dcConfiguration: Optional, iOS 26+ only. Configures Digital Credentials API support for presenting credentials via an OS-native overlay. Specify your app group and supported document types (e.g., .mDL, .eudi, .euav, .photoid, .jpMnc).

mobileCredentialHolder.initialize(
    activity,
    userAuthenticationConfiguration = UserAuthenticationConfiguration( 
        behavior = UserAuthenticationBehavior.Always, 
        presentationTimeoutSeconds = 20
    ),
    credentialIssuanceConfiguration = CredentialIssuanceConfiguration(
        redirectUri = "<WalletRedirectUri>", 
        autoTrustMobileCredentialIaca = true
    )
)

• userAuthenticationConfiguration: Optional. Configures when the SDK requires user authentication to access or present credentials. The example shows the default values. Refer to the reference documentation for additional details about the available configuration options.
• redirectUri : Provide a URL that corresponds to a specific path in your application. The SDK will redirect the user to this path after they successfully complete authentication. Required for the Authorization Code flow.
• autoTrustMobileCredentialIaca : Set to true if you trust the credential issuer(s) for any offer. Defaults to false.

const initializeResult = await mobileCredentialHolder.initialize({
  userAuthenticationConfiguration: {
    userAuthenticationBehavior: UserAuthenticationBehavior.OnInitialize, 
    userAuthenticationType: UserAuthenticationType.BiometricOrPasscode, 
  },
  credentialIssuanceConfiguration: {
    autoTrustMobileCredentialIaca: true, 
    redirectUri: "<WalletRedirectUri>", 
  },
});
if (initializeResult.isErr()) {
  const { error } = initializeResult;
  // handle error scenarios
  return;
}

• userAuthenticationConfiguration: Optional. Configures when the SDK requires user authentication to access or present credentials. Refer to the reference documentation for additional details about the available configuration options.
• redirectUri: Provide a URL that corresponds to a specific path in your application. The SDK will redirect the user to this path after they successfully complete authentication. Required for the Authorization Code flow.
• autoTrustMobileCredentialIaca: Set to true if you trust the credential issuer(s) for any offer. Defaults to false.

    let discoveredOffer = try await mobileCredentialHolder.discoverCredentialOffer(offerUrl: String)

• offerUrl : Pass the OID4VCI initiation URL.

The discoverCredentialOffer method returns a DiscoveredCredentialOffer object containing the offer details.

val discoveredOffer = mobileCredentialHolder.discoverCredentialOffer(offerUri)

• offerUrl : Pass the OID4VCI initiation URL as a string.

The discoverCredentialOffer method returns an instance of DiscoveredCredentialOffer containing the offer details.

const discoveredOfferResult =
  await mobileCredentialHolder.discoverCredentialOffer(offerUrl); 
if (discoveredOfferResult.isErr()) {
  const { error } = discoveredOfferResult;
  // handle error scenarios
  return;
}
const credentialOffer = discoveredOfferResult.value;

• offerUrl : Pass the OID4VCI initiation URL.

The discoverCredentialOffer method returns a Result<CredentialOfferResponse, Error> (using the neverthrow pattern) object containing the offer details and/or any errors.

let retrievedCredentialResults = try await mobileCredentialHolder.retrieveCredentials(
    credentialOffer: String, 
    clientId: "<WalletClientID>", 
    transactionCode: nil
)

• credentialOffer : Pass the OID4VCI credential offer URI.
• clientId : Pass a string that identifies your wallet application with the issuer.
• transactionCode : Provide a transaction code if the Pre-Authorization Code flow offer requires a transaction code.

The retrieveCredentials method returns an array of RetrieveCredentialResult objects, each containing the metadata of the retrieved credentials, including the credential ID (credentialId).

val credentialResults = mobileCredentialHolder.retrieveCredentials(
    activity = activity,
    credentialOffer = offerUri, 
    clientId = "<WalletClientID>", 
    transactionCode = null
)

• credentialOffer : Pass the OID4VCI credential offer URI.
• clientId : Pass a string that identifies your wallet application with the issuer.
• transactionCode : Provide a transaction code if claiming a credential using a Pre-authorized Code flow that requires a transaction code.

The retrieveCredentials method returns an array of RetrieveCredentialResult objects, each containing the metadata of the retrieved credentials, including the credential ID (credentialId).

const retrievedCredentialsResults =
  await mobileCredentialHolder.retrieveCredentials({
    credentialOffer: offerUrl, 
    clientId: "<WalletClientID>", 
    transactionCode: undefined, 
  });
if (retrievedCredentialsResults.isErr()) {
  const { error } = retrievedCredentialsResults;
  // handle error scenarios
  return;
}
const retrievedCredentials = retrievedCredentialsResults.value;

const retrievedCredential = retrievedCredentials[0];
if (retrievedCredential?.error || !retrievedCredential?.credentialId) {
  // handle error scenarios
  return;
}
const credentialId = retrievedCredential.credentialId;

• credentialOffer: Pass the OID4VCI credential offer URI.
• clientId: Pass a string that identifies your wallet application with the issuer.
• transactionCode: Provide a transaction code if the Pre-Authorization Code flow offer requires a transaction code.

The retrieveCredentials method returns a Result<RetrieveCredentialsResponse, Error> (using the neverthrow pattern) object containing the metadata of the retrieved credentials, including the credential ID (credentialId).

let credential = try mobileCredentialHolder.getCredential(credentialId: String)

• credentialId : Pass the credential ID of the credential you want to access.

val credential = mobileCredentialHolder.getCredential(credentialId)

• credentialId : Pass the credential ID of the credential you want to access, as a string.

const credentialResult =
  await mobileCredentialHolder.getCredential(credentialId); 
if (credentialResult.isErr()) {
  const { error } = credentialResult;
  // handle error scenarios
  return;
}
const credential = credentialResult.value;

• credentialId : Pass the credential ID of the credential you want to access.

Ensure that your application is registered to handle the verifier's authorization URL. This is typically done in the app's Info.plist file. The URL scheme should match the one used by the verifier.

Ensure that your application is registered to handle the verifier's authorization URL. This is typically done in the AndroidManifest.xml file. The URL scheme should match the one used by the verifier.

Ensure that your application is registered to handle the verifier's authorization URL. The URL scheme should match the one used by the verifier.

• For iOS this is typically done in the app's Info.plist file.
• For Android this is typically done in the AndroidManifest.xml file.

    let onlinePresentationSession = try await mobileCredentialHolder.createOnlinePresentationSession(authorizationRequestUri: authorizationRequestURI, requireTrustedVerifier: false)

• authorizationRequestURI : Pass the OID4VP authorization request URI as a string.
• requireTrustedVerifier : Set to true if you want to ensure that the verifier exists on the app's trusted verifier's list.

The createOnlinePresentationSession method returns an instance of OnlinePresentationSession containing requested and matching credentials.

    val onlinePresentationSession = mobileCredentialHolder.createOnlinePresentationSession(
        authorisationRequestUri = authorizationRequestUri,
        requireTrustedVerifier = false
    )

• authorisationRequestURI : Pass the OID4VP authorization request URI as a string.
• requireTrustedVerifier : Set to true if you want to ensure that the verifier exists on the app's trusted verifier's list.

The createOnlinePresentationSession method returns an instance of OnlinePresentationSession containing requested and matching credentials.

const createSessionResult =
  await mobileCredentialHolder.createOnlinePresentationSession({
    authorizationRequestUri: authorizationRequestURI,
    requireTrustedVerifier: false,
  });
if (createSessionResult.isErr()) {
  const { error } = createSessionResult;
  // handle error scenarios
  return;
}
const onlinePresentationSession = createSessionResult.value;

• authorizationRequestUri : Pass the OID4VP authorization request URI as a string.
• requireTrustedVerifier : Set to true if you want to ensure that the verifier exists on the app's trusted verifier's list.

The createOnlinePresentationSession method returns an instance of OnlinePresentationSession containing requested and matching credentials.

    let credential = try await mobileCredentialHolder.getCredential(credentialId: id)

• id : Pass the identifier of the credential you want to present, as a string. This information can be retrieved from the OnlinePresentationSession object returned by the createOnlinePresentationSession method.

Your application must then gather the user's consent to share the matching credential with the verifier.

    val credential = mobileCredentialHolder.getCredential(credentialId)

• credentialId : Pass the identifier of the credential you want to present, as a string. This information can be retrieved from the OnlinePresentationSession object returned by the createOnlinePresentationSession method.

Your application must then gather the user's consent to share the matching credential with the verifier.

const credentialResult = await mobileCredentialHolder.getCredential(
  credentialId, 
);
if (credentialResult.isErr()) {
  const { error } = credentialResult;
  // handle error scenarios
  return;
}
const credential = credentialResult.value;

• credentialId : Pass the identifier of the credential you want to present, as a string. This information can be retrieved from the OnlinePresentationSession object returned by the method.

Your application must then gather the user's consent to share the matching credential with the verifier.

    try await onlinePresentationSession.sendResponse(credentialIds: [id])

• id : Pass the identifier of the credential you want to send, as a string.

onlinePresentationSession.sendResponse(
    credentialIds = listOf(credentialId), 
    activity = activity
)

• credentialId : Pass the identifier of the credential you want to send, as a string.

const sendResponseResult = await onlinePresentationSession.sendResponse({
  credentialIds: [credentialId],
});
if (sendResponseResult.isErr()) {
  const { error } = sendResponseResult;
  // handle error scenarios
  return;
}

• credentialId : Pass the identifier of the credential you want to send, as a string.

    let proximityPresentationSession = try await mobileCredentialHolder.createProximityPresentationSession(
                    onRequestReceived: onRequestReceived(_:error:)
                    // 1. Callback triggered when the verifier requests a credential for verification. Use this callback to display the request on the UI and get the user's consent to share any matched credentials.
                )

The createProximityPresentationSession method returns an instance of ProximityPresentationSession which contains a deviceEngagement property that must be shared with the verifier embedded in a QR code to establish a secure connection.

val proximityPresentationSession = mobileCredentialHolder.createProximityPresentationSession(
    onRequestReceived = { session, matchedCredentials, error ->
        if (error != null) {
             // Handle error
        } else {
            // 1. Show request on UI
            // 2. Show matched credentials on UI and get user's consent to share them
            // 3:
            session.sendResponse(
                val credentialIds = matchedCredentials!!.flatMap {
                    it.matchedCredentials.map { credential -> credential.id }
                } ,
                activity = activity
            )
        }
    }
)

The createProximityPresentationSession method returns an instance of ProximityPresentationSession which contains a deviceEngagement property that must be shared with the verifier embedded in a QR code to establish a secure connection.

const createSessionResult =
  await mobileCredentialHolder.createProximityPresentationSession({
    onRequestReceived: (data) => {
      if ("error" in data) {
        // handle error scenarios
        return;
      }

      // 1. Show UI prompt and gather user consent
      // 2. Retrieve matching credential from request object
    },
  });
if (createSessionResult.isErr()) {
  const { error } = createSessionResult;
  // handle error scenarios
  return;
}
const proximityPresentationSession = createSessionResult.value;

The createProximityPresentationSession method returns an instance of ProximityPresentationSession which contains a deviceEngagement property that must be shared with the verifier embedded in a QR code to establish a secure connection.

    let credential = try await mobileCredentialHolder.getCredential(credentialId: id)

• id : Pass the identifier of the credential you want to present, as a string. This information is returned by the createProximityPresentationSession method on a onRequestReceived event, triggered when the verifier requests a credential for verification.

Your application must then gather the user's consent to share the matching credential with the verifier.

    val credential = mobileCredentialHolder.getCredential(credentialId)

• credentialId : Pass the identifier of the credential you want to present, as a string. This information is returned by the createProximityPresentationSession method on a onRequestReceived event, triggered when the verifier requests a credential for verification.

Your application must then gather the user's consent to share the matching credential with the verifier.

const credentialResult =
  await mobileCredentialHolder.getCredential(credentialId); 
if (credentialResult.isErr()) {
  const { error } = credentialResult;
  // handle error scenarios
  return;
}
const credential = credentialResult.value;

//
// Send a response to the verifier
//
const sendResponseResult =
  await mobileCredentialHolder.sendProximityPresentationResponse({
    credentialIds: [credentialId],
    terminateSession: false,
  });
if (sendResponseResult.isErr()) {
  const { error } = sendResponseResult;
  // handle error scenarios
  return;
}

• credentialId : Pass the identifier of the credential you want to present, as a string. This information is returned by the createProximityPresentationSession method on a onRequestReceived event, triggered when the verifier requests a credential for verification.

Your application must then gather the user's consent to share the matching credential with the verifier.

    try await proximityPresentationSession.sendResponse(credentialIds: [id])

• id : Pass the identifier of the credential you want to send, as a string.

    proximityPresentationSession?.sendResponse(credentialIds = listOf(credentialId))

• credentialId : Pass the identifier of the credential you want to send, as a string.

const sendResponseResult =
  await mobileCredentialHolder.sendProximityPresentationResponse({
    credentialIds: [credentialId],
  });
if (sendResponseResult.isErr()) {
  const { error } = sendResponseResult;
  // handle error scenarios
  return;
}

• credentialId : Pass the identifier of the credential you want to send, as a string.