Verify Documentation

1.0.0 [23-04-2021]

General

About TypingDNA?

TypingDNA builds products that analyze user typing behavior to make conclusions. One application of our technology is verification of user identity for authentication purposes.

Our Verify and Authentication API solutions commonly replace traditional second factor authentication flows, enabling users to confirm their identity by typing -- without the additional UX friction introduced by more traditional methods.

About Verify

Verify is a complete 2FA service designed to reduce reliance on traditional SMS and Email 2FA methods in the user authentication process. A Verify integration allows you to offer typing verification as a second factor in flows where traditional 2FA methods would otherwise have been required.

With Verify, end-users prove their identity by typing generated texts, only deferring to Root of Trust channels (SMS & Email) when strictly necessary. In most cases, when typing verification succeeds, codes are instead displayed on-screen or passed via a callback to the client application, depending on how the integration is configured.

The goal of Verify is to offer the best experience to end-users while reducing the costs typically associated with sending 2FA codes.

Who is this guide for?

Verify is an appropriate solution for application owners looking to improve the 2FA process for their users. Verify is a managed 2FA service that is designed for simple integration and an optimized UX -- end-user typing pattern collection, verification, and fallback logic is handled by TypingDNA, capturing data from users directly.

Compared to our RESTful Authentication API product, Verify is less customizable and is designed to replace a specific 2FA application flow. If you want to leverage typing pattern matching in a non-2FA context, or require advanced settings configuration and more flexible architecture/application flow support, consider the Authentication API.

Initial Setup

Sign up for an account

To integrate Verify you will need to obtain credentials (Client ID & Secret) and create your first application. Sign up for a free account to get started, and sign in to the Client Dashboard for access to your Client ID & Secret.

Configure your account

Below are the steps required within the dashboard to configure a Verify account before beginning the integration process:

Connect providers

In order to send SMS or email verification codes to your users, a corresponding channel provider account must be linked from within the Verify Dashboard. In both Sandbox and Production environments, these credentials will be used on your behalf to send a verification code to the user via the channel provided for that end-user from the backend.

Failure to connect a channel account will result in an error message if an attempt is made to verify or enroll a user through that channel.

1. Connect a Twilio account

In order to send SMS verification codes on your behalf, we require you associate a Twilio account with your TypingDNA Verify account. Click the Connect to Twilio button within the Dashboard to grant our application the required access.

Existing users will be prompted to login to their Twilio account, while new users will be given the option to sign up for the service.

2. Connect a Sendgrid account

To support email verification codes, a Sendgrid account must be associated with your account. Link an existing account or create a new one through the Connect to Sendgrid button within the Verify Dashboard.

Create an Application

All user enrollment and verification activity in Verify occurs within the context of an Application. To create your first application, click on the Add your first integration button from within the Dashboard.

Add Application details

Each Application requires a domain to be associated with it. This field is mandatory, and used to ensure proper and secure communication between the TypingDNA Verify window and the origin website that initiated the Verify process. Provide the domain that will be hosting the front-end snippet that renders the Verify button.

It is important to set the correct domain, as using a different domain than what is configured will result in an error.

Overview

Summary

TypingDNA Verify is designed to reduce the number of SMS/email 2FA codes required to be sent to your users, replacing them with in-browser, secure typing biometric verification when possible.

Users launch the secure Verify window from within a client application by integrating a TypingDNA backend client, frontend JavaScript and HTML snippet that renders a button to launch the service. The backend client passes the required data attributes to the frontend, linking them to the button via HTML attributes on the button element. When an end-user clicks the button, these values are passed to the Verify window to identify the end-user, determine if they are existing users or not, and handle verification according to the settings/preferences passed.

There are three scenarios in which typing biometrics verification is not possible, and traditional SMS/email verification codes are sent.

First, when a user initially registers their typing behavior with TypingDNA through the Verify window, a verification code is sent to the registered channel (SMS or email) to establish a Root of Trust (RoT).

Second, when a user fails typing verification, the service will defer to the RoT registered during enrollment to confirm their identity.

Finally, when an end-user’s device is determined to be mobile, a code is automatically sent, as typing verification is currently not supported on mobile.

How encrypted end-user data and verification results flow between your backend, frontend and the Verify window depends on the mode you have chosen when initializing the TypingDNAVerifyClient object in the backend. There are two available modes, which to choose depends on UX preference:

Standard mode

To implement Standard mode, a callback function has to be included in the data attributes of the HTML button through which the TypingDNA Verify popup is opened (see Integrate Backend). After the user has attempted typing verification in the Verify window, if the user’s pattern is verified successfully, a verification code is returned as a parameter to the callback function. If the user fails verification, the error message is passed in the same parameter.

Show OTP mode

After the verification process has finished and the user has inserted the code into the input field on your frontend, a request to your backend is made with the code. The typingDNAVerifyClient.validateOTP() method is then called to confirm the authenticity of the verification code using TypingDNA’s validation service.This method requires both the user identifier and code as parameters (see Reference section for details).

If the code is valid a success message will be returned. Otherwise, the code validation service will return a failure to validate message.

Integrate Backend & Frontend

Integrate Backend

Once an account is set up in the Dashboard, the next step is to install an official TypingDNA client in the backend and configure it according to your preferences.

This guide will use the Verify JavaScript npm module for examples. Support for additional languages (JavaScript, Java, PHP/Python/C#/Ruby in progress) exists and is available on Github.

Get the Verify client

The first step in the backend integration process is to retrieve the TypingDNA Verify client. The NodeJS Verify client is installable via npm:

npm install typingdna-verify-client

Initialize the TypingDNAVerifyClient

Once installed, the client is initialized, submitting account credentials generated in previous steps in the Dashboard as parameters:

const typingDNAVerifyClient = new TypingDNAVerifyClient({ 
              clientId: "",
              applicationId: "",
              secret: ""
           });

Pass user data to the frontend

Once initialized, the next step is to retrieve end-user data in the backend, for encryption and linking with the frontend button created in the next step.

The getDataAttributes method is called to pass credentials and encrypted user data to the frontend snippet. Both the language and mode are optional parameters, defaulting to ‘EN’ and ‘standard’ respectively. Support for additional languages is in progress.

const typingDNADataAttributes = typingDNAVerifyClient.getDataAttributes({ 
                email,
                phoneNumber,
                language :  'en',
                mode : 'standard' // 'show_otp' alternatively
             });

Integrate Frontend

With the backend configured, the next step is to retrieve the frontend script that renders the button which opens the Verify window.

Get the frontend JavaScript

Retrieve the frontend JavaScript from the following link:

<script src = "https://cdn.typingdna.com/verify/typingdna-verify.js"></script>

Add a button element to your HTML

After you’ve determined the location within a page the ‘Verify’ button should be placed, add a button element with a ‘TypingDNAVerify’ class and the data attributes below. These attributes correspond to values in the TypingDNADataAttributes object passed from the backend (clientId, applicationId, and payload) and will be passed to the Verify window once clicked by an end-user.

<button
      class = "typingdna-verify"
      data-typingdna-client-id= typingDNADataAttributes.clientId
      data-typingdna-application-id= typingDNADataAttributes.applicationId
      data-typingdna-payload= typingDNADataAttributes.payload
      data-typingdna-callback-fn= "callbackFn"> Verify with TypingDNA
</button>

The class, data-typingdna-client-id and data-typingdna-payload are mandatory attributes for the frontend to be linked properly with the data retrieved from the backend.

In addition to the required attributes, optional values exist for additional configuration:

typingdna-method: This attribute defines the HTTP method (POST or GET) used to communicate with the Verify window. With POST (default), the end-user’s data will not be visible to them from within the window.

typingdna-callback-fn: If you’ve configured the backend mode data attribute to be standard, this function will be passed the user’s verification code automatically as a parameter once generated (the end-user has verified successfully in the window). In the case of an error, the error details will be returned as a parameter instead.

Reference

Backend public methods

The methods available in the Verify client and their function are as follows:

getDataAttributes({ email, phoneNumber, countryCode, language }): A helper method that wraps every required data-attribute on the frontend. This triggers when the user clicks on the Verify with TypingDNA button.

validateOTP({ email, phoneNumber, countryCode }, code): This method is used in the client’s backend to validate the OTP the user has submitted. The function calls the TypingDNA code validation service and returns either a success or failure. Upon a successful code validation, the end-user is considered verified.

sendOTP({ email, phoneNumber, countryCode }): This method manually triggers the sending of a verification code from the client’s backend to the user’s email or phone. This bypasses the Verify window’s typing verification flow, and is useful for scenarios in which users cannot type to confirm their identity, such as access via a mobile device.

Language codes

By default, end-users will be served the Verify window in English. This can be changed via the ‘language’ parameter of the getDataAttributes method of the Verify backend client. Support for the additional languages below is in progress and the table will be updated as new languages become available.

Language Code
Englishen
SpanishIn progress
RomanianIn progress
PortugueseIn progress
FrenchIn progress
GermanIn progress
ItalianIn progress
DutchIn progress
KoreanIn progress
Chinese (Mandarin)In progress
JapaneseIn progress
RussianIn progress

Error messages

Code Status Message
104400Invalid request body
105400Invalid client id
106400Invalid application id
107500Internal server error
108400Request has expired
109400Missing user identifier
116500Error validating OTP
124400Unauthorized request
126401Operation not allowed