Email Code

Verification with an email code is another type of built-in verification. When an end user starts registering on a device for the first time, a 6-digit code is sent to the email address that they are registering with. A screen where they can enter the code is displayed on the device where they started the verification. They can open the email with the code on any device, and when they enter the code on the device where they started the registration, the verification completes.

IMPORTANT: If an end user wants to reset their PIN, i.e. starts verifying on a device that has already been registered, a code will be sent to their email address. However, they might want to add a new device when they have already registered another one with their email address. In that case, a link will be sent to them even if your project’s verification method is set to Email Code. This is done to avoid the risk of phishing attacks.

# Configure the Email Code Verification

To use Email Code as a verification method, you must set it up in the MIRACL Trust Portal. To do so:

  1. Go to your project in the MIRACL Trust Portal.
  2. Select User Verification under Configuration.
  3. Use the Verification Method dropdown list to select the Email Code option.

# Integrate in Your Application

MIRACL Trust’s built-in verification can be integrated directly into your applications through the platform’s Mobile SDKs and Client JS Library, which enable the implementation of verification flows.

The verification starts by calling the sendVerificationEmail method of the MIRACL Trust Android SDK, MIRACL Trust iOS SDK or MIRACL Trust Client JS Library.


miraclTrust.sendVerificationEmail(
    userId = USER_ID,
    resultHandler = ResultHandler { result ->
        when (result) {
            is MIRACLSuccess -> {
                // Verification email is sent.
            }
            is MIRACLError -> {
                val error = result.value
                // Verification email is not sent due to an error.
            }
        }
    }
)

miraclTrust.sendVerificationEmail(
    USER_ID,
    result -> {
        if (result instanceof MIRACLSuccess) {
            // Verification email is sent.
        } else {
            MIRACLError<VerificationResponse, VerificationException> error =
                    (MIRACLError<VerificationResponse, VerificationException>)
                            result;
            // Verification email is not sent due to an error.
        }
    }
);

    MIRACLTrust.getInstance().sendVerificationEmail(
        userId: <#Unique user identifier (any string, i.e. email)#>
    ) { (verificationResponse, error) in
        // Check here if verification email is sent and handle any verification errors.
    }

    [[MIRACLTrust getInstance]
        sendVerificationEmailWithUserId: <#Unique user identifier#>
            authenticationSessionDetails: nil
                    completionHandler: ^(VerificationResponse *verificationResponse, NSError * _Nullable error) {
                        // Check here if verification email
                        // is sent and handle any verification errors.
                    }];

mcl.sendVerificationEmail(userId, function (error, result) {
  if (error) {
    // Handle any potential errors
    console.error(error);

    return;
  }

  console.log(result);
});

Then, a verification email is sent, and a verification response with backoff is returned. A backoff is the period you must wait before you making new verification request; otherwise, you will receive a backoff error.

If the end user has already registered another device with the same User ID, a Verification URL will be sent, and the verification method in the response will be link. In this case, proceed as described for the Email Link verification method.

If the end user is registering for the first time or resetting their PIN, an email with a verification code will be sent, and the email verification method in the response will be code. Then, ask the user to enter the code in the application.

When the end user enters the code, the application must confirm the verification by calling the getActivationToken method of the MIRACL Trust Android SDK, MIRACL Trust iOS SDK or MIRACL Trust Client JS Library:

miraclTrust.getActivationToken(userId, code) { result ->
    when (result) {
        is MIRACLSuccess -> {
            val userId = result.value.userId
            val activationToken = result.value.activationToken

            // Use the activation token and the User ID to register the user.
        }

        is MIRACLError -> {
            val error = result.value
            // Cannot obtain activation token due to an error.
        }
    }
}

miraclTrust.getActivationToken(userId, code, result -> {
    if (result instanceof MIRACLSuccess) {
        ActivationTokenResponse response =
                ((MIRACLSuccess<ActivationTokenResponse, ActivationTokenException>)
                        result).getValue();

        String userId = response.getUserId();
        String activationToken = response.getActivationToken();

        // Use the activation token and the User ID to register the user.
    } else {
        MIRACLError<ActivationTokenResponse,
                ActivationTokenException> error =
                (MIRACLError<ActivationTokenResponse, ActivationTokenException>)
                        result;
        // Cannot obtain activation token due to an error.
    }
});

MIRACLTrust
    .getInstance()
    .getActivationToken(userId: userId, code: code) { activationTokenResponse, error in
        // Pass the activation token to the `register` method.
    }

[[MIRACLTrust getInstance]
 getActivationTokenWithUserId:userId
 code:code
 completionHandler:^(ActivationTokenResponse * _Nullable response, NSError * _Nullable error) {

    // Pass the activation token to the `register` method.
}];

mcl.getActivationToken(
  "https://yourdomain.com/verification/confirmation?userId=alice@miracl.com&code=theVerificationCode",
  function callback(err, result) {
    if (err) {
      // Handle any potential errors
    }

    console.log(result.actToken);
  },
);

The result of the verification confirmation is an activation token. Use it to call the register method of the MIRACL Trust Android SDK, MIRACL Trust iOS SDK or MIRACL Trust Client JS Library. When a PIN is requested, prompt the end user to enter one.

miraclTrust.register(
    userId = USER_ID,
    activationToken = activationToken,
    pinProvider = { pinConsumer ->
        // Ask the user to create a PIN code for their new User ID.
        // Then pass the PIN code to the PinConsumer.
        pinConsumer.consume(userPin)
    },
    resultHandler = { result ->
        when (result) {
            is MIRACLSuccess -> {
                val user = result.value
            }

            is MIRACLError -> {
                val error = result.value
                // Cannot register a user due to an error.
            }
        }
    }
)

miraclTrust.register(
    USER_ID,
    activationToken,
    pinConsumer -> {
        // Ask the user to create a PIN code for their new User ID.
        // Then pass the PIN code to the PinConsumer.
        pinConsumer.consume(userPin);
    },
    result -> {
        if (result instanceof MIRACLSuccess) {
            User user = ((MIRACLSuccess<User, RegistrationException>) result).getValue();
        } else {
            MIRACLError<User, RegistrationException> error =
                    (MIRACLError<User, RegistrationException>) result;
            // Cannot register user due to an error.
        }
    }
);

MIRACLTrust.getInstance().register(
    for: <#Unique user identifier (any string, i.e. email)#>,
    activationToken: <#Activation token#>,
    didRequestPinHandler: { pinProcessor in
        // Here the user creates a PIN code for their new User ID.

        pinProcessor(<#Provide your PIN code here#>)
    },
    completionHandler: { user, error in
    // Get the user object or handle the error appropriately.
    }
)

[[MIRACLTrust getInstance] registerFor:<#Unique user identifier (any string, i.e. email)#>
                    activationToken:<#Activation token#>
                pushNotificationsToken:<#Push notifications token#>
                didRequestPinHandler:^(void (^ _Nonnull pinProcessor)(NSString *)) {
                    // Here the user creates a PIN code for their new User ID.

                    pinProcessor(<#Provide your PIN code here#>)
                } completionHandler:^(User * _Nullable user, NSError * _Nullable error) {
                    // Get the user object or handle the error appropriately.
                }];

mcl.register(
  userId,
  actToken,
  function (passPin) {
    // Here you need to prompt the user for their PIN
    // and then call the passPin argument with the value
    passPin(pin);
  },
  function callback(err) {
    if (err) {
      // Handle any potential errors
    }
  },
);

If the registration is successful, the enrolment process is completed. End users can now authenticate using the PIN chosen for the device. They can go through the verification process for each device they want to use for authentication or use QuickCode, if enabled, to enrol additional devices using the already enrolled one.