Custom User Verification

# Introduction

Verification is the process that enrols a device with cryptographic material used for future authentications. With the M-PIN Authentication Protocol, an authentication cannot occur without a User ID that has been provisioned in advance. There are no restrictions on how the verification is performed — it can be online (e.g., email or SMS) or offline (e.g., the user presenting their government-issued ID to a representative).

By default, MIRACL Trust uses email verification. However, if you need a custom process, you can implement your own using Custom User Verification. In this case, you are responsible for verifying your end users, and MIRACL Trust relies on your verification to issue a User ID.

For example, a bank may require users to verify their identity by uploading a photo of a government-issued ID and completing a short video selfie. Once the user passes this check, the bank’s system confirms the verification to MIRACL Trust, which then issues the User ID needed for authentication.

# How It Works

Custom User Verification enables you to design and implement any verification flow. You are responsible for verifying the User ID of the end user and submitting the verification result to the MIRACL Trust platform, which then generates a Verification URL.

Once the client application receives the Verification URL, it must confirm the verification by calling the getActivationToken method. This step is handled automatically if you use the MIRACL Trust authorisation page or the MIRACL Trust Authenticator. Otherwise, you can use the getActivationToken method of the Client JS Library, or the Android or iOS or Flutter libraries.

Next, the end user is prompted to choose a PIN. Once the PIN is entered and confirmed, the enrolment process is complete and the device is provisioned with a User ID.

From that point on, the end user can authenticate using their chosen PIN on that device. If they wish to use additional devices, they can either repeat the verification process for each one or use QuickCode to enrol new devices using a previously enrolled one.

# Configure Custom User Verification

Before implementing Custom User Verification, configure your settings in the MIRACL Trust Portal:

  1. Log in to the MIRACL Trust Portal and select your project.
  2. In the Configuration menu, choose User Verification.
  3. From the Verification Method dropdown, select Custom. This unlocks the following additional configuration options:

  • Custom Verification URL: This is the link on your system where end users are redirected to initiate the verification process if they attempt to log in without a pre-registered User ID.

    Note: Custom Verification URL is different from Verification URL.

    • Custom Verification URL is the registration URL in your system that you set up in the MIRACL Trust Portal.
    • Verification URL is the platform-issued URL that is used to transfer the verification to the platform, finishing the verification flow.

  • Custom Verification Text - Before being redirected to the Custom Verification URL, the end user sees a screen with verification instructions. You can customise this message. The default text is:

    We need to verify this device before you can register. Select Start Verification to be redirected to the verification page.

  • User ID Type - By default, MIRACL Trust uses email addresses as end-user identifiers. If your Custom User Verification process uses other identifiers (usernames, account numbers, or other custom IDs), switch the User ID Type to Alphanumeric.

  • User ID Text - The label displayed when referring to the end-user identifier. If you set the User ID Text to Email, it defaults to Email. If you set it to Alphanumeric, it defaults to User ID.

Important: Configuring Custom User Verification incurs additional costs for your account.

# Implement the Verification

Once the end user’s User ID has been verified through your custom process, you need to request the Verification URL from the MIRACL Trust platform. The Verification URL is generated by making an authenticated POST request to https://api.mpin.io/verification.

The end user must follow the URL from the response to enrol a new device.

See MIRACL Trust Backend API for more details.

For integration-specific information about implementing Custom User Verification, see the relevant articles: