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:
state string to correlate the session with a record in your own system (see
Correlate sessions with your own records using state).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
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 of a wallet provider created on the MATTR VII verifier tenant.
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
when creating a verifier application.
stateWhen you create a presentation session, MATTR VII generates its own sessionId (a UUID) to track the session through
its lifecycle. That identifier is meaningful within MATTR VII, but it does not map to anything in your own system. If
you need to attach a verification to an existing record on your side, such as an onboarding application, a checkout
intent, or an account opening flow, pass an optional state string to requestCredentials().
state is an opaque correlation reference that you generate and control. MATTR VII carries it through the verification
session and returns it to you with the result, so no additional state management is required in your application or
backend. The value:
If you only need to verify a credential and act on the result immediately in the same browser session, state is not
required; the MATTR VII sessionId is enough on its own. Use state when correlation needs to survive the round-trip
to the wallet and back.
The
statevalue is transmitted in plain text as a query parameter on the wallet-facing authorization request URI and is stored in session records. It should not contain personally identifiable information (PII), credentials, or anything sensitive. Use an opaque reference, such as an internal record ID or a randomly generated token your system can map back to the underlying record.
stateis a correlation reference, not a security mechanism. It does not replace thechallengeused to detect session replay. Continue to generate a uniquechallengeper session and validate it against the result you receive.
statePass state alongside the other options when calling requestCredentials():
const options: MATTRVerifierSDK.RequestCredentialsOptions = {
credentialQuery: [credentialQuery],
challenge: MATTRVerifierSDK.utils.generateChallenge(),
state: "onboarding-app-7f3a4e8c", // Your own opaque correlation reference
openid4vpConfiguration: {
redirectUri: window.location.origin,
walletProviderId,
},
};
const results = await MATTRVerifierSDK.requestCredentials(options);
The SDK requires state to be a non-empty string. The MATTR VII platform additionally enforces a maximum length of 256
characters and rejects an empty or over-length value with an HTTP 400 validation error. If your internal identifier is
longer, store it on your side and pass a shorter reference that maps back to it.
When state is not supplied, the OpenID4VP state claim falls back to the MATTR VII sessionId, no state field
appears in the result, and existing integrations see no change in behavior.
For the complete end-to-end flow across both the MATTR VII platform and the SDK, see the Correlating verification sessions with your system guide on MATTR Learn.
state backstate is echoed back wherever a session result is exposed. In cross-device flows it is returned on the
RequestCredentialsResponse resolved by requestCredentials():
const results = await MATTRVerifierSDK.requestCredentials(options);
if (results.isOk()) {
const { state, result } = results.value; // state === "onboarding-app-7f3a4e8c"
// Use state to look up the matching record in your system.
}
In same-device flows it is returned on the HandleRedirectCallbackResponse resolved by handleRedirectCallback() on
your redirect page:
const results = await MATTRVerifierSDK.handleRedirectCallback();
if (results.isOk()) {
const { sessionId, state, result } = results.value; // state === "onboarding-app-7f3a4e8c"
}
For same-device flows, the SDK persists
statetolocalStoragebefore redirecting to the wallet and removes it afterhandleRedirectCallback()completes. This is an implementation detail that guards against frameworks stripping query parameters from redirect URIs; you do not need to read or write this storage entry yourself.
When your verifier application delivers results through the back channel (resultAvailableInFrontChannel: false), the
same state field is included in the response from the retrieve presentation session result endpoint, on both success
and failure shapes.
For the full end-to-end pattern, including a worked onboarding example and the back-channel result flow across both the MATTR VII platform and the SDK, see the Correlating verification sessions with your system guide on MATTR Learn.
DC API support is currently offered as a tech preview. As such, functionality may be limited, may not work in all scenarios, and could change or break without prior notice.
Add the dcApiConfiguration object to your MATTR VII
verifier application configuration.
Use the SDK's isDigitalCredentialsApiSupported method to determine if the user's browser supports the Digital
Credentials API:
import * as MattrVerifierSDK from "@mattrglobal/verifier-sdk-web";
const isDcApiSupported = MattrVerifierSDK.isDigitalCredentialsApiSupported();
This returns true if the browser supports DC API, false otherwise.
requestCredentials, conditionally set the walletProviderId based on DC API support:const options: MattrVerifierSDK.RequestCredentialsOptions = {
credentialQuery: [credentialQuery],
challenge: MattrVerifierSDK.utils.generateChallenge(),
openid4vpConfiguration: {
redirectUri: window.location.origin,
walletProviderId: isDcApiSupported ? undefined : "your-wallet-provider-id",
},
};
const results = await MattrVerifierSDK.requestCredentials(options);
The Verifier Web SDK uses the DC API only when all of the following conditions are met:
isDigitalCredentialsApiSupported() returns true).walletProviderId is provided in the request options.If any condition is not met, the SDK falls back to the standard OID4VP flow.
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
state: "YOUR-REFERENCE-ID", // Optional: attach your own correlation reference
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 failure", result.error);
} else {
console.info("<<< MATTRVerifierSDK.requestCredentials succeed", 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 identifiers of a
wallet provider
created on the MATTR VII verifier tenant..state (optional): Your own opaque correlation reference for this presentation session. Do not include personally
identifiable information (PII), credentials, or anything sensitive, as the value is transmitted in plain text on the
wallet-facing request URI and stored in session records. Returned in the response from requestCredentials()
(cross-device) or handleRedirectCallback() (same-device). See
Correlate sessions with your own records using state.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.MATTRVerifierSDK.initialize({ apiBaseUrl, applicationId });
const result = await MATTRVerifierSDK.requestCredentials({
credentialQuery: credentialQuery,
challenge: MATTRVerifierSDK.utils.generateChallenge(),
state: "YOUR-REFERENCE-ID", // Optional
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();
// result.value contains { sessionId, state, result? }
});
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(),
state: "YOUR-REFERENCE-ID", // Optional
openid4vpConfiguration: {
walletProviderId,
mode: "crossDevice",
},
});
if (result.isErr()) {
console.info("<<< MATTRVerifierSDK.requestCredentials failure", result.error);
} else {
console.info("<<< MATTRVerifierSDK.requestCredentials succeed", 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.
state parameter to requestCredentials(). Pass an opaque correlation reference, such as an
internal record ID, to link a verification session to a record in your own system without maintaining a separate
sessionId mapping. MATTR VII carries the value through the session and returns it with the result in both
same-device and cross-device flows, on both successful and failed results. See
Correlating verification sessions with your system.Updated internal dependencies to address known vulnerabilities and improve overall security stability.
This is a maintenance release. It includes code refactoring and improvements to support future capabilities.
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