Request or download the MATTR Pi SDK Trial License 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 mDocs, supporting both same-device and cross-device verification workflows. The SDK leverages the MATTR VII platform to handle credential presentation and verification processes.
In this SDK mDocs are referred to as Mobile Credentials.
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.initialize(...);
<script src="https://cdn.mattr.global/js/verifier-sdk-web/{VERSION}/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.initialize(...);
</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 initialize the SDK before you can use any of its functions and methods:
MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
apiBaseUrl (required): URL of the MATTR VII verifier tenant.applicationId (required): Unique identifier of the verifier application. This must match the id parameter in the response returned when creating a Verifier application configuration on the MATTR VII verifier tenant.The following example credential query will request the given_name, family_name, birth_date 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": {
"given_name": {
"intentToRetain": false
},
"family_name": {
"intentToRetain": false
},
"birth_date": {
"intentToRetain": false
},
"portrait": {
"intentToRetain": false
},
"resident_postal_code": {
"intentToRetain": false
}
},
}
}
];
profile: Credential format of the credential that will be verified. Currently only mobile (mDocs) is supported.docType: the mDL’s type. Confirm with the certificate issuer for what docType they are issuing. Some common examples include:org.iso.18013.5.1.mDL).org.iso.23220.photoid.1).org.iso.7367.1.mVRC).org.micov.vtr.1).nameSpaces: Each namespace corresponds to a group of claims included in the credential. These can be claims that are part of a specific standard, jurisdiction or any other reference. The namespace would usually correspond to the requested docType.intentToRetain (Optional): When set to true, the holder will be indicated that the verifier intends to retain this claim beyond the verification workflow. Defaults to false when not specified.The API supports including multiple query objects in the
credentialQueryarray in a single request. For simplicity, this example only includes a single query object.
In this example the credentialQuery query will request for the birthdate, portrait and resident_postal_code claims from any credentials whose profile is mobile and docType is org.iso.18013.5.1.mDL.
It also sets intentToRetain as false for all claims, indicating to the holder that the verifier will not retain any of these claims.
While
intentToRetaindefaults to false, it is explicitly set tofalsein the example above for clarity purposes. If there is no intention to retain a claim, it is sufficient to simply excludeintentToRetainfrom the 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.initialize({ apiBaseUrl, applicationId }); // Initialize the SDK
const result = await MATTRVerifierSDK.requestCredentials({
credentialQuery: [credentialQuery], // Define what credential query to use
challenge: MATTRVerifierSDK.utils.generateChallenge(), // Pass a unique challenge
openid4vpConfiguration: {
walletProviderId, // Define the wallet identifier
redirectUri, // Define the redirect URI (not required for cross-device only requests)
}
});
if (result.isErr()) {
console.info("<<< MATTRVerifierSDK.requestCredentials succeed", result.error);
} else {
console.info("<<< MATTRVerifierSDK.requestCredentials failure", result.value);
}
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 application configuration.MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
const result = await MATTRVerifierSDK.requestCredentials({
credentialQuery: [credentialQuery],
challenge: MATTRVerifierSDK.utils.generateChallenge(),
openid4vpConfiguration: {
redirectUri,
walletProviderId,
mode: "sameDevice",
}
});
// result can be retrieved on redirect uri page. for example
window.addEventListener("load", async () => {
MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
const result = await MATTRVerifierSDK.handleRedirectCallback();
});
mode: When set to sameDevice, the SDK will only support same-device flow in this verification workflow.redirectUri.MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
const result = await MATTRVerifierSDK.requestCredentials({
credentialQuery: [credentialQuery],
challenge: MATTRVerifierSDK.utils.generateChallenge(),
openid4vpConfiguration: {
walletProviderId,
mode: "crossDevice",
}
});
if (result.isErr()) {
console.info("<<< MATTRVerifierSDK.requestCredentials succeed", result.error);
} else {
console.info("<<< MATTRVerifierSDK.requestCredentials failure", result.value);
}
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.
OpenIdvpConfiguration type for requestCredentials optionsintialise method:
intialise method was renamed to initializeInitialiseOptions type was renamed to InitializeOptionsinitialize method now requires providing an applicationId to identify a specific web application interacting
with the MATTR VII verifier tenant.The values in the Mode enum were renamed to use PascalCase:
crossDevice was renamed to CrossDevicesameDevice was renamed to SameDevicerequestCredentials method:
RequestCredentialsSameDeviceOptions,
RequestCredentialsCrossDeviceDeviceOptions, and RequestCredentialsAutoDetectOptions. Instead,
walletProviderId, mode, and redirectUri are grouped inside an optional openid4vpConfiguration attribute
which can be used to differentiate between presentation modes:mode as SameDevice and provide redirectUrimode as CrossDevice and omit redirectUrimode and provide redirectUricrossDeviceCallback option which contains the onComplete
and onFailure callback functions. Instead the function will await for the session to complete and return a
Result. The Result will contain the presentation result on success, or an error with the failure reason.Window.open() method, or on top-level windows that have a single history entry. The returned
value now contains a sessionCompletedInRedirect: true property to indicate if the flow has continue on the
redirect page.Invalid credentials included in presentations will no longer result in a PresentationFailureResult, but instead a
PresentationSuccessResult containing details of which credentials have failed verification and why. The verification
response structure was updated to allow this:
MobileCredentialVerificationReasonType now includes a number of extra possible values:
TrustedIssuerCertificateExpired, TrustedIssuerCertificateNotYetValid, IssuerNotTrusted,
MobileCredentialInvalid, MobileCredentialExpired, MobileCredentialNotYetValid, InvalidSignerCertificate,
DeviceKeyInvalid, UnsupportedCurve, StatusRevoked, StatusSuspended, StatusUnknown and no longer includes
expired, inactive, invalid, suspended, unknown
abortCredentialRequest method for aborting the currently active credentials request session. Any in-progress
requestCredentials invocation will resolve immediately with an error result with the
RequestCredentialsErrorType.Abort error type.initialise method now takes an optional applicationId to identify a specific web application interacting with
the MATTR VII verifier tenant.CrossDeviceCallbackOnCompleteResponse and HandleRedirectCallbackResponse will return sessionId on the top levelMobileCredentialVerificationReasonType now includes values specific to mobile credential revocation status:
StatusRevoked, StatusSuspended, StatusUnknownGenerated using TypeDoc