Request or download the MATTR Pi SDK Trial Licence Agreement and the MATTR Customer Agreement and review these terms carefully.
The Verifier Web SDK is a powerful tool for integrating online credential verification capabilities into your web applications. It enables secure and efficient verification of Mobile Credentials, supporting both same-device and cross-device verification workflows. The SDK leverages the MATTR VII platform to handle credential presentation and verification processes.
Refer to our SDK Docs landing page for step-by-step instructions to gain access to any of our SDKs.
Please reach out if you need any assistance.
yarn add @mattrglobal/verifier-sdk-web
import * as MATTRVerifierSDK from "@mattrglobal/verifier-sdk-web";
MATTRVerifierSDK.initialise(...);
<script src="https://cdn.mattr.global/js/verifier-sdk-web/1.0/verifier-js.production.js"></script>
This script will automatically pick up any SDK patch updates. You can lock your implementation to a specific patch version by replacing 1.0 with the specific version (e.g. https://cdn.mattr.global/js/verifier-sdk-web/1.0.1/verifier-js.production.js).
MATTRVerifierSDK object.<script>
MATTRVerifierSDK.initialise(...);
</script>
The SDK can make a request to create a presentation session with a configured MATTR VII verifier tenant. This requires the following configurations and settings:
You must initialise the SDK before you can use any of its functions and methods.
When initialising the SDK, you must provide the URL of the MATTR VII verifier tenant.
The following example credential query will request the birthdate and portrait claims from a mobile credential profile with org.iso.18013.5.1.mDL as a docType:
const credentialQuery = {
"profile": "mobile",
"docType": "org.iso.18013.5.1.mDL",
"nameSpaces": {
"org.iso.18013.5.1": {
"birthdate": {
"intentToRetain": false
},
"portrait": {},
"resident_postal_code": {
"intentToRetain": false
}
},
}
};
The API supports multiple queries in one request. For simplicity, this example only includes a single query.
The Verifier Web SDK passes a unique challenge to the MATTR VII verifier tenant with every request to create a new presentation session. The purpose of the challenge is to ensure the security and integrity of the credential verification process by preventing replay attacks and verifying the authenticity of each request and response. You can either:
When the challenge is generated by your backend, you should use it to validate the verification results received from the MATTR VII verifier tenant.
The same-device flow involves the user completing all steps on a single device, such as their smartphone. They initiate the credential request on the verifier's web app, are redirected to their wallet app to consent and present credentials, and then return to the verifier's web app with the results.
In contrast, the cross-device flow starts on one device, like a laptop. When the user initiates the request, the web app responds by displaying a QR code. The user then scans this QR code with their smartphone, use their wallet app to present matching credentials, and the results are sent back to the verifier's web app.
The main difference is that the same-device flow uses only one device for the entire process, while the cross-device flow uses two devices for added flexibility.
By default, the Verifier Web SDK automatically selects a flow based on the browser's user agent:
This behavior can be explicitly overridden by specifying the desired mode in the SDK configuration, as shown in the examples below.
You can define an identifier of a specific wallet you want to invoke with this verification request. The identifier defined by the SDK in the credential request must match one of the identifiers defined in the walletProviders array of the MATTR VII tenant's verifier configuration.
id of one of the objects in the walletProviders array, the verifier tenant will invoke that specific wallet using its corresponding authorizationEndpoint.id of any of the objects in the walletProviders array, the request will fail.mdoc-openid4vp:// (default OID4VP scheme) to invoke any wallet.When using the same-device presentation flow, the SDK must define what URI to redirect the user to once they complete the verification workflow in their wallet app. This can be any URI (including custom URI schemes), and must match one of the values defined in the redirectUris array in the MATTR VII tenant's verifier configuration.
MATTRVerifierSDK.initialise({ apiBaseUrl }); // Initialise the SDK
const result = await MATTRVerifierSDK.requestCredentials({
credentialQuery: [credentialQuery], // Define what credential query to use
challenge: MATTRVerifierSDK.utils.generateChallenge(), // Pass a unique challenge
walletProviderId, // Define the wallet identifier
redirectUri, // Define the redirect URI (not required for cross-device only requests)
crossDeviceCallback: { // Define how to handle completion/failure of cross-device flows (not required for same-device only requests)
onComplete: (result) => {
console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onComplete", result);
},
onFailure: (error) => {
console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onFailure", error);
},
},
});
apiBaseUrl : Replace with the tenant_url of your MATTR VII verifier tenant.credentialQuery: The credential query to be used in the request.challenge: The challenge that will be passed to the MATTR VII tenant with the request to create a presentation session. This example uses the SDK built-in method to generate the challenge, but you can replace it with a challenge generated by your backend system.walletProviderId: Replace with a wallet identifier that matches one of the values in the walletProviders array of the MATTR VII tenant's verifier configuration.mode: When omitted, the SDK defaults to automatically selecting a flow based on the browser's user agent (set to undefined in the example for clarity).redirectUri Replace with a URI that matches one of the values in the redirectUris array in the MATTR VII tenant's verifier configuration.crossDeviceCallback: Defines how to handle completion (onComplete) or failure (onFailure) of the verification workflow.MATTRVerifierSDK.initialise({ apiBaseUrl });
const result = await MATTRVerifierSDK.requestCredentials({
credentialQuery: [credentialQuery],
challenge: MATTRVerifierSDK.utils.generateChallenge(),
redirectUri,
walletProviderId,
mode: "sameDevice",
});
// result can be retrieved on redirect uri page. for example
window.addEventListener("load", async () => {
MATTRVerifierSDK.initialise({ apiBaseUrl });
const result = await MATTRVerifierSDK.handleRedirectCallback();
});
mode: When set to sameDevice, the SDK will only support same-device flow in this verification workflow.redirectUri.MATTRVerifierSDK.initialise({ apiBaseUrl });
const result = await MATTRVerifierSDK.requestCredentials({
credentialQuery: [credentialQuery],
challenge: MATTRVerifierSDK.utils.generateChallenge(),
walletProviderId,
mode: "crossDevice",
crossDeviceCallback: {
onComplete: (result) => {
console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onComplete", result);
},
onFailure: (error) => {
console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onFailure", error);
},
},
});
mode: When set to crossDevice, the SDK will only support cross-device flow in this verification workflow.The SDK includes mechanisms for handling errors, such as invalid requests, session timeouts, and user aborts. Callbacks provide detailed error information to help diagnose and remedy issues.
Generated using TypeDoc