Verify 2FA Documentation

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 2FA 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.

Integrate Verify 2FA in under 10 minutes inside your web app. Follow along...

To integrate Verify 2FA 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.

The Sandbox environment allows you to get familiarized with the TypingDNA Verify 2FA technology. The Sandbox environment is limited to a maximum of 1000 users per month.

The Production environment is designed for live applications. Production environment also benefits from our federated model, which means that if a user has already enrolled on one website application, they will not need to enroll again on other websites that use TypingDNA Verify technology.

The Production environment for the Starter plan is free to use and is limited to 1000 active users per month. The Pro Production environment has no limit on the number of users and can be activated instantly by introducing a valid credit card.

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

Connect providers

TypingDNA will provide the first 200 OTP codes in the Sandbox environment, after that 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, after the first 200 OTP codes are sent, 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 2FA 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 2FA Dashboard.

Create an Application

All user enrollment and verification activity in Verify 2FA 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 2FA window and the origin website that initiated the Verify 2FA process. Provide the domain that will be hosting the front-end snippet that renders the Verify 2FA button.

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

TypingDNA Verify 2FA 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 2FA 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 2FA 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 2FA 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 2FA 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 2FA popup is opened (see Integrate Backend). After the user has attempted typing verification in the Verify 2FA 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.

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 2FA 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 2FA client

The first step in the backend integration process is to retrieve the TypingDNA Verify 2FA client. The NodeJS Verify 2FA 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 (note: credentials differ between the sandbox and production environments):

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

With the backend configured, the next step is to retrieve the frontend script that renders the button which opens the Verify 2FA 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 2FA’ 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 2FA 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 2FA 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 2FA 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.

The methods available in the Verify 2FA 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 2FA 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 2FA 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.

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