Getting Started

There are just a few simple steps that are required to begin using our authentication API and to receive Keystroke DNA signature scores:

  1. Identify the input fields to be verified with Keystroke DNA.
  2. Include KeystokeDNA.js into your HTML.
  3. Set up input fields using HTML attributes.

Identifying Input Fields

You can choose as many different fields as you would like to be validated by Keystroke DNA and any text input field is acceptable for use. The chosen input field also serves as the user identifier for Keystroke DNA's validation process.

The only required criterion is that the text input field is sufficiently long and contains at least 8 characters.

Password input fields can also be used but they require a specific grant_type to make sure that the password is never recorded and remains confidential at all times.

Let's define what a UserID is ...

Any unique identifier of a user can be used as the UserID with Keystroke DNA including username, student or corporate ID, email address, credit card, phone number, and any other unique user identifier. As the userID’s sole purpose is to identify and distinguish users, a depersonalized identifier generated by your system may also be utlized.

Code changes

There are few changes required in the client side and server side code to begin using Keystroke DNA.

Client-side changes

Loading Keystroke API code Libraries

To start using Keystroke DNA, you will need to include a loading script at the bottom of the body section of your webpage to asynchronously load the plugin:

You will require your API Key and Secret, which can be obtained by Joining Beta Program.

The KSDNA_SDK_URL variable contains a version number v0.4.1 that indicates the latest major release of our API and your {{your_api_key}} that is obtained through joining our Beta Program

Setting Up Input Fields

There can be one or more fields that are validated with Keystroke DNA and each of these input fields should be marked with the ksdna attribute. However, there should only be a single user identifier input field for each unique user, which must be marked with the ksdna-uid attribute.

email and phrase fields will be will be analyzed with Keystroke DNA

Initializing the library

After all the input fields have been created, the following script should be added to signal that all the necessary fields have been established and are set up with Keystroke DNA tags:

Submitting your form

Next you have to modify your form handler and add the required KSDNA data to your request.

You can select your own names for fields e.g. signature and value and then operate with these on the server-side.

Server-side changes

Configuration extension

If you already have a configuration for your web application, then you have to include the two additional constants below:

YOUR_KSDNA_APP_ID and YOUR_KSDNA_APP_SECRET as noted above are obtained through Our Beta Program.

Getting a Bearer token

Next, you have to obtain a bearer token to authorize your calls to our API.

We utilize JSON Web Tokens (JWT) to authorize API calls. Each JWT can be used to authorize multiple API calls and is valid for up to 9999 seconds. Please note that there is a limit to the number of new JWTs accepted from the same domain of one new JWT every three seconds.

cURL

The response from us will be a standard JWT token.

Scoring a Keystroke DNA signature

The biometric data that are submitted to our service of your users’ typing rhythms and patterns are called Keystroke DNA signatures and the authentication score we return is called the Keystroke DNA signature score or signature score for short. At this point, you are now fully equipped to begin receiving Keystroke DNA signature scores of your users' typing patterns through our service.

The code below illustrates how to enhance the security of your log-in process with Keystroke DNA, for example, as a second or third authentication factor but you can also implement Keystroke DNA in many other ways to increase access security and perform additional authentication and identity checks.

cURL

There are a few key points to keep in mind when integrating Keystroke DNA into your web application:

  1. The username value can be read from any single field of your form (e.g. in a listing) or it can be assigned explicitly (e.g. an email hashed with a salt, or a UUID4 from a loaded by email user, etc.) but it must be unique for our system.
  2. You have to proxy a real User-Agent of your client to us as this field is mandatory and is used by our service.
  3. Fields value and signature are already prepared on the client-side so you can just proxy those.
  4. You have to use your Bearer token to authenticate yourself for this call.

If the integration process was successful, you will receive a response similar to below:

Key Terms:

Receiving a signature score of -1.0

A signature score of -1.0 is returned by Keystroke DNA’s authentication API under a few different scenarios including:

  1. When onboarding every new user for the first time:

    • The first time a Keystroke DNA signature is sent to be scored, (i) a biometric profile for the user is established, (ii) the userid for such user is created in the system, and (iii) a signature score of -1.0 is returned by default.
    • In this case, our response will include the message {"code": "first_sequence"}
  2. If a Keystroke DNA signature has not been completed properly, for example, characters have been entered incorrectly, there is insufficient data available to generate a score, or a session timeout occurs, then a signature score of -1.0 can be returned.

  3. The first time a registered system user with userid enters a Keystroke DNA signature from a new device, which has a significantly different keyboard or touchscreen layout from their original device, the user’s typing patterns will naturally be different and a signature score of -1.0 will also returned and will include the message {"code": "new_device"}

Please note that Keystroke DNA signatures containing less than 8 input characters will produce the following system error message:

New Device Approval and Security

To begin using a new device, a new biometric user profile must be created that is specific to such new device. Because system breaches and fraud almost always originate from new and previously unrecognized and unapproved devices, all new devices should be approved to maintain security.

Keystroke DNA offers several different methods to approve new devices. From a security perspective, we recommend using a device that has already been previously approved in order to approve the new device.

Pre-Approved Device Approval Method

New device approval can be performed by asking the user to sign in with one of their previously used and approved devices. End users can be asked to sign in again with a previously used and approved device by, for example, sending them an email link or by using a pop-up prompt. Following a successful sign on a pre-approved device, the response from our system will include the “notApproved” block below:

The required code from the response above, which in this example case is 2a7117QCrqQb70R4hfeGjVD2vxBQ must be used to approve the new device.

The new device can then be approved by initiating the following API call:

Following device approval, our system will create a biometric profile for the new device that can be used to receive Keystroke DNA signature scores going forward.

Admin Device Approval Method

In certain use cases, it may be appropriate for client admins to approve the use of new devices from their backend without requiring end users to authenticate with a pre-approved device. This should only be done only in cases where client admins are certain that the new device belongs to and is being used by a genuine user.

To approve a new device using the Admin Device Approval method, the following API call should be initiated by the client:

Following device approval, our system will create a biometric profile for the new device that can be used to receive Keystroke DNA signature scores going forward.