KeyTrac Quickstart

The fast track integration of KeyTrac for all developers who want be finished in no time

Register for a KeyTrac account

Before getting started, you'll need to Register for a KeyTrac account and confirm your email address. The KeyTrac API uses an API token to authenticate your requests. You'll find this token in your Management Console. Without an account you're not able to use KeyTrac!

Integrate the KeyTrac Recorder

The KeyTrac Recorder is an easy to use JavaScript which is responsible for recording the keystroke dynamics of a user. It needs to be embedded into your website, including all websites where you want to record the typing behavior of users.

1) Load the KeyTrac Recorder JavaScript

Add the following script tag to (preferably) the head section of your website. This loads and includes the KeyTrac Recorder. When the Recorder JavaScript was successfully embedded, the KeyTrac Recorder is available for use.

<script type="text/javascript" src="https://api.keytrac.net/keytrac.js"></script>

2) Bind the recorder to input fields

To enable the KeyTrac Recorder, it must be bound to the input fields that should be used with KeyTrac. This is done through passing an array of DOM-Identifiers of the input fields that should be used with KeyTrac prefixed with a # to the KeyTrac.configure method.

For simplicity we'll using the anytextFields option to instruct the KeyTrac Recorder to listen for keystrokes in the given fields in AnyText mode. Input fields which are not explicitly configured will be ignored by the Recorder. The method shown below is only suitable for AnyText use cases. (For Password Hardening mode click here)

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    <title>KeyTrac Enrolment Demo</title>
    <link rel="stylesheet" type="text/css" href="styles.css">
    <script type="text/javascript" src="https://api.keytrac.net/keytrac.js"></script>
  </head>
  <body>
    <!-- The form which contains all input fields -->
    <form action="/enrol" method="post">
      <p>This is the text users need to enter in the textarea below</p>
      <textarea name="textArea1" id="textArea01"></textarea>
      <p>This is the text users need to enter in the textarea below</p>
      <textarea name="textArea2" id="textArea02"></textarea>
      <input type="submit" value="Enrol me!">
    </form>

    <!-- Configuration of the KeyTrac Recorder -->
    <script type="text/javascript">
      KeyTrac.configure({
        anytextFields: ['#textArea01', '#textArea02'] // <-- AnyText mode
      });
    </script>
  </body>
</html>

3) Verify the state of the KeyTrac Recorder

When the KeyTrac Recorder is successfully embedded and the page was reloaded, the Recorder dynamically adds hidden fields below each configured input fields. If these fields don't appear, there's something wrong with the integration of the JavaScript. Please use the inspector tool of your browser to verify the state of the integration. Check whether the hidden fields with the name prefix keytrac_ are existing.

...
<!-- The textarea where users type in something -->
<textarea name="textArea1" id="textArea01"></textarea>
<!-- The hidden field which records the keystroke dynamics -->
<input type="hidden" name="keytrac_textArea01" id="keytrac_textArea01">
...
<!-- The textarea where users type in something -->
<textarea name="textArea2" id="textArea02"></textarea>
<!-- The hidden field which records the keystroke dynamics -->
<input type="hidden" name="keytrac_textArea02" id="keytrac_textArea02">
...

Create a KeyTrac user ID

Rule of thumb: You need to create a user in KeyTrac for every user in your web application.

A user in KeyTrac reflects an actual user of your web application. You can think of a KeyTrac user as a kind of an assignment unit which anonymously stores the keystroke dynamics of a single user.

User Creation Sequence Diagram

  1. A user signs up for a new account on your website.
  2. You request a new KeyTrac user identifier for that user.
  3. KeyTrac API returns an unique identifier, you need to store with the other user data.

1) Create a new user

When you create a new user in KeyTrac, the API system responds with an unique user identifier. You can think of this identifier as a kind of ID Card of a user in the whole KeyTrac system.

$ curl -d '' -H "Authorization: <<YOUR AUTHENTICATION TOKEN>>" https://api.keytrac.net/users

{"id":"8f5a2308-90b5-4afa-8847-ebf2b99f4082"}

The user identifier 8f5a2308-90b5-4afa-8847-ebf2b99f4082 is used exemplary in the whole documentation and may not reflect an actual user identifier!

As this user identifier is important for KeyTrac, it needs to be stored along with other user data in the database on your side. To automate the creation of such a KeyTrac user, just integrate it into your user registration workflow of your web application. So, if the user was successfully created in you web application, also create it on the KeyTrac side!

Record the user's keystroke dynamics

Now, let's assume that you've already set up a corresponding KeyTrac user identifier (for example 8f5a2308-90b5-4afa-8847-ebf2b99f4082) for a user account in your web application. In order to continue, it's required that the user types something into the text-areas of the prepared form of section Bind the recorder to input fields. While the user is typing, the KeyTrac Recorder is recording and preparing the keystroke dynamics of the user in a processable format.

User Input

After the user has finished typing, the form is submitted with a POST request and your web application takes control. Now use the values of the parameters keytrac_textArea01 and keytrac_textArea02 and keep them for Teaching KeyTrac the keystroke dynamics where you'll teach KeyTrac with that keystroke dynamics.

Teaching KeyTrac the keystroke dynamics

Rule of thumb: Before you're able to enroll users, you have to create them first!

To make KeyTrac able to work, it needs to learn the typing pattern of your previously created and active user. This training is done during an enrollment process where the recorded keystroke dynamics are transformed into a user profile which is utilized for later authentication requests.

Enrollment Sequence Diagram

  1. Your website, where the KeyTrac JavaScript Recorder is embedded, gets loaded.
  2. On form submit, the recorded keystroke dynamics is sent to your backend.
  3. Take the typing sample(s) and the KeyTrac user ID, assemble both and send it to KeyTrac API.
  4. KeyTrac API creates a new user profile out of the given typing sample(s).

1) Prepare the required JSON data

Before you're able to do the enrollment, you need to prepare the JSON data as shown below in order to communicate with the KeyTrac API system. The data in the samples array are the recorded keystroke dynamics of the submitted parameters generated through the hidden fields keytrac_textArea01 and keytrac_textArea02 of the form in section Verify the state of the KeyTrac Recorder, whereas the user_id refers to the user identifier, created in section Create a new User.

{
  "user_id":"8f5a2308-90b5-4afa-8847-ebf2b99f4082",
  "samples":[
    "firefox/38.0#m=0#2016-01-29 17:50:51|0dRSHIFT|320d84|48uRSHIFT",
    "firefox/38.0#m=0#2016-01-29 17:50:59|0dRSHIFT|310d84|40uRSHIFT"
  ]
}

2) Enroll/Teach a user profile

Now, after preparing the required JSON data structure, you're able to teach KeyTrac the keystroke dynamics of the user with the identifier 826efc1d-78e5-4e69-b144-de090de6094b. This is done with POSTing the JSON data as payload to the KeyTrac API system. If everything is set up right, the API responds with {"OK:true"}. For demonstration, this is executed manually with the following curl command.

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<YOUR AUTHENTICATION TOKEN>>" \
  -d '{"user_id":"<<USER ID FROM STEP [Create a KeyTrac user ID]>>","samples":[
    "firefox/38.0#m=0#2016-04-25 09:22:52|336dRSHIFT|80d68|64uRSHIFT|32u68|32d73|80u73|8d69|72dSPACE|16u69|88uSPACE|64d66|72u66|64d69|80d78|18u69|62u78|104d85|72u85|32d84|64d90|8u84|88u90|8d84|48d69|48u84|72u69|8dSPACE|88uSPACE|96dRSHIFT|40d77|64uRSHIFT|24d69|40u77|40u69|120d84|72u84|16d72|88d79|17u72|31d68|72u68|8u79|56d69|88u69|72dSPACE|80uSPACE|48d66|56u66|72d69|80u69|56d83|56d84|40u83|40d69|48u84|64u69|168d72|104u72|32d84|72u84|72dSPACE|72uSPACE|48d73|96d78|64dSPACE|32u73|16u78|40d68|40uSPACE|32u68|72d69|48d82|64u69|8dSPACE|32u82|48uSPACE|88dLSHIFT|96d77|32uLSHIFT|56u77|48d69|72u69|152d83|72u83|96d83|88u83|8d85|72u85|112d78|80d71|8u78|56u71|40dSPACE|56d68|40uSPACE|32u68|88d69|40d82|40u69|40u82|8dSPACE|64dLSHIFT|16uSPACE|80d76|64uLSHIFT|16u76|88d85|16d70|48u85|40u70|72d84|64u84|32d190|48u190",
    "firefox/38.0#m=0#2016-04-25 09:24:58|128dRSHIFT|568d68|64uRSHIFT|32u68|192d73|40u73|88d69|88u69|160dSPACE|88uSPACE|8d66|72u66|40d69|88d78|8u69|96u78|104d85|80d84|8u85|88u84|40d90|80d84|16u90|56d69|32u84|64u69|64dSPACE|80uSPACE|72dRSHIFT|64d77|72uRSHIFT|8d69|48u77|16u69|40d84|80u84|32d72|88d79|32u72|32d68|32u79|40u68|88d69|64dSPACE|8u69|88uSPACE|40d66|96u66|496d69|72u69|88d83|88d84|40u83|48d69|40u84|40d72|16u69|96u72|40d84|80u84|72dSPACE|96uSPACE|104d73|64d78|56u73|24dSPACE|56u78|8d68|56uSPACE|32u68|80d69|48d82|48u69|56u82|16dSPACE|64dLSHIFT|32uSPACE|120d77|8uLSHIFT|80d69|8u77|64u69|88d83|56u83|96d83|64d85|16u83|56u85|104d78|80d71|8u78|56u71|8dSPACE|88d68|16uSPACE|72u68|80d69|48d82|56u69|56u82|8dSPACE|72uSPACE|32dLSHIFT|64d76|72uLSHIFT|0u76|88d85|25d70|55u85|16u70|80d84|56u84|56d190|24u190"]}' \
  https://api.keytrac.net/anytext/enrol

{"OK":true}

With this API call executed you've built the foundation for further API actions, the authentication request. To trigger the teaching process automatically, your web application needs to be extended to perform this action right after the form submission of section Record the user's keystroke dynamics.

Authenticate previously created user

Rule of thumb: Before you're able to authenticate users, you first have to enroll them!

Authentication Sequence Diagram

  1. Your website, where the KeyTrac JavaScript Recorder is embedded, gets loaded.
  2. On form submit, the recorded keystroke dynamics is sent to your backend.
  3. Take the typing sample(s) and the KeyTrac user ID, assemble both and send it to KeyTrac API.
  4. KeyTrac API computes a match-score of the given typing sample(s) compared to those in the user profile.
  5. Use the recommendation from KeyTrac to accept or reject the user's authentication attempt.

When you've accomplished all the previous steps, you're now able to perform your first authentication of the previously created user. But before you can rev up, you need to record the keystroke dynamics accordingly to section Record the user's keystroke dynamics. So please create another HTML document like the one in section Bind the recorder to input fields.

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta http-equiv="content-type" content="text/html; charset=utf-8">
    <title>KeyTrac Authentication Demo</title>
    <link rel="stylesheet" type="text/css" href="styles.css">
    <script type="text/javascript" src="https://api.keytrac.net/keytrac.js"></script>
  </head>
  <body>
    <!-- The form which contains all input fields -->
    <form action="/authenticate" method="post">
      <p>Another text to be entered in the textarea below</p>
      <textarea name="textArea" id="textArea"></textarea>
      <input type="submit" value="Authenticate me!">
    </form>

    <!-- Configuration of the KeyTrac Recorder -->
    <script type="text/javascript">
      KeyTrac.configure({
        anytextFields: ['#textArea'] // <-- AnyText mode
      });
    </script>
  </body>
</html>

After the user has finished typing, the form is also submitted with a POST request and your web application takes control. Now use the values of the parameter keytrac_textArea and keep it for the next step where you'll use it in order to authenticate with that keystroke dynamics.

1) Prepare the required JSON data

For ease of use, the structure of JSON data required for the authentication request remains the same as used for the enrollment request. So the data in the samples array is the recorded keystroke dynamics of the submitted hidden field keytrac_textArea, whereas the user_id refers to the user identifier, created in section Create a new user.

{
  "user_id":"8f5a2308-90b5-4afa-8847-ebf2b99f4082",
  "samples":[
    "firefox/38.0#m=0#2016-01-29 17:50:51|0dRSHIFT|320d84|48uRSHIFT"
  ]
}

2) Authenticate against the user's profile

After preparing the required JSON data structure, you're now able to authenticate against the stored keystroke dynamics profile of the user with the identifier 826efc1d-78e5-4e69-b144-de090de6094b. This needs to be done with POSTing the JSON data as payload to the KeyTrac API system.

Once your request succeeds, the KeyTrac web service either returns true if the submitted typing sample matches to the stored profile of the user, otherwise it returns false. Additionally, the web service returns a percentual match-score, indicating the similarity of the submitted typing sample(s) to the stored typing profile of the user. The higher the score, the higher is the matching. The minimum score is 0. The maximum score is 100. Scores are integer values. Example: {"authenticated":true, "score":95}

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<YOUR AUTHENTICATION TOKEN>>" \
  -d '{"user_id":"<<USER ID FROM STEP [Create a KeyTrac user ID]>>","samples":["firefox/38.0#m=0#2016-04-25 09:26:37|400dRSHIFT|88d68|25uRSHIFT|55u68|32d73|64d69|8u73|80u69|8dSPACE|72uSPACE|48d66|72u66|80d69|88u69|96d78|80u78|96d85|80d84|1u85|79u84|16d90|64d84|24u90|8d69|56u84|56u69|32dSPACE|56uSPACE|224dLSHIFT|88d77|48uLSHIFT|48u77|24d69|64u69|104d84|72u84|24d72|120d79|8u72|40d68|48u79|32u68|72d69|80u69|24dSPACE|96uSPACE|24d66|56u66|88d69|80u69|96d83|104d84|16d69|32u83|48u84|32u69|8d72|112u72|40d84|64u84|136dSPACE|96uSPACE|120d73|88d78|72dSPACE|8u73|32u78|32d68|32uSPACE|24u68|72d69|56d82|48u69|32dSPACE|16u82|64uSPACE|176dLSHIFT|80d77|72uLSHIFT|0u77|80d69|64u69|104d83|56u83|80d83|104u83|1d85|63u85|104d78|72d71|8u78|64u71|32dSPACE|64d68|16uSPACE|56u68|80d69|40d82|40u69|48u82|616dSPACE|72uSPACE|16dLSHIFT|88d76|64uLSHIFT|1u76|112d85|47d70|8u85|48u70|80d84|64u84|40d190|32u190"]}' \
  https://api.keytrac.net/anytext/authenticate

{"authenticated":true, "score":95}

Instead of a manual execution of this request you can automate the authentication of a KeyTrac user by integrating the KeyTrac authentication into your user authentication workflow of your web application.