@mattrglobal/verifier-sdk-web

verifier-sdk-web

Table of Contents

• Licensing
• Overview
• Features
• Getting started
• Usage
  • Initialise the SDK
  • Prepare the credential query
  • Select walletId
  • Generate challenge
  • Determine device request mode
  • Request credentials to support both same device and cross device
  • Request credentials with explicit same device mode
  • Request credentials with explicit cross device mode
• Error Handling

Licensing

Request or download the MATTR Pi SDK Trial Licence Agreement and the MATTR Customer Agreement and review these terms carefully.

Overview

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 verifiable credentials, supporting both same-device and cross-device flows. The SDK leverages the MATTR VII platform to handle credential presentation and verification processes.

Features

• Simple integration into web applications.
• Supports both same-device and cross-device presentation flows.
• Secure handling of credential requests and responses.
• Compliant with ISO/IEC DTS 18013-7.

Getting started

How to get access to the MATTR Pi Verifier Web SDK

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.

Installation

For web project with an existing bundler set up

1. Install dependencies via npm:

npm install --save @mattrglobal/verifier-sdk-web

2. Import the sdk module in your code:

import * as MATTRVerifierSDK from "@mattrglobal/verifier-sdk-web";

MATTRVerifierSDK.initialise(...);

Loading directly from script tag

1. Install dev dependencies via npm:

npm install --save-dev @mattrglobal/verifier-sdk-web

2. Serve verifier-js.production.js from your web server (You can find it under node_module/@mattrglobal/verifier-sdk-web/dist/verifier-js.production.js) and load it via a script tag from your web page:

<script src="https://..../verifier-js.production.js"></script>

3. Access SDK functions via global MATTRVerifierSDK object.

<script> 
   MATTRVerifierSDK.initialise(...);
</script> 

Usage

Initialise the SDK

MATTRVerifierSDK.initialise({ apiBaseUrl });

[!NOTE] The apiBaseUrl should be the tenant_url of your MATTR VII verifier tenant.

Prepare the credential query

Example credential query to request the birthdate and portrait claims in a mobile credential of type org.iso.18013.5.1.mDL:

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
      }
    },
  }
};

[!NOTE] The API supports multiple queries in one request. For simplicity, this example only includes a single query.

Select walletId

The walletId and redirectUri parameters are defined as part of your MATTR VII tenant verifier configuration. and must match the values provided in the credential request (see examples below).

Refer to the API Reference for more information on these parameters and how to set them.

Generate challenge

The purpose of generating a 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. Refer to the examples below that demonstrate how to generate this challenge as part of the credential request.

Determine presentation flow

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, where the user initiates the request and receives a QR code. They then scan this QR code with their smartphone, use their wallet app to present 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 detects whether to use the same-device or cross-device flow based on the browser's user agent. However, this behavior can be explicitly overridden by specifying the desired mode in the SDK configuration.

Request credentials to support both same device and cross device

MATTRVerifierSDK.initialise({ apiBaseUrl });
const result = await MATTRVerifierSDK.requestCredentials({
  credentialQuery: [credentialQuery],
  challenge: MATTRVerifierSDK.utils.generateChallenge(),
  walletId,
  mode: undefined, // auto detection base on browser user agent
  redirectUri, // required fields for save device mode
  crossDeviceCallback: { // required fields for cross device mode
    onSuccess: (result) => {
      console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onSuccess", result);
    },
    onFailure: (error) => {
      console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onFailure", error);
    },
  },
});

Request credentials with explicit same device mode

MATTRVerifierSDK.initialise({ apiBaseUrl });
const result = await MATTRVerifierSDK.requestCredentials({
  credentialQuery: [credentialQuery],
  challenge: MATTRVerifierSDK.utils.generateChallenge(),
  redirectUri,
  walletId,
  mode: "sameDevice",
});

// result can be retrieved on redirect uri page. for example
window.addEventListener("load", async () => {
  MATTRVerifierSDK.initialise({ apiBaseUrl });
  const result = await MATTRVerifierSDK.handleRedirectCallback();
});

Request credentials with explicit cross device mode

MATTRVerifierSDK.initialise({ apiBaseUrl });
const result = await MATTRVerifierSDK.requestCredentials({
  credentialQuery: [credentialQuery],
  challenge: MATTRVerifierSDK.utils.generateChallenge(),
  walletId,
  mode: "crossDevice",
  crossDeviceCallback: {
    onSuccess: (result) => {
      console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onSuccess", result);
    },
    onFailure: (error) => {
      console.info("<<< MATTRVerifierSDK.requestCredentials crossDeviceCallback.onFailure", error);
    },
  },
});

Error Handling

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.