API Documentation

Our RESTful API can be used from any programming language able to speak HTTP

Overview

The KeyTrac API is a powerful keyboard biometrics web service that gives you various options to use the keystroke dynamics of your users for authentication purposes. The KeyTrac API also offers analyzing options to track and inspect the authentication behavior of your users.

API Hostname

Our API is available under https://api.keytrac.net and all your communication needs to go to this hostname. For security reasons, the KeyTrac API is only available through HTTPS. (Learn more)

Submitting HTTP requests

For a better illustration on how you'll communicate with KeyTrac API, we use curl, a simple Terminal HTTP client which is available for most operating systems. As KeyTrac API requires only little effort on exchanging data, we're only need the following options:

Option switch Definition of this option switch
-H Adds an HTTP header which is sent to KeyTrac API (learn more)
-d Sends the specified data to KeyTrac API (learn more)

Security and API authentication

1) Transmission Security

For security reasons, the KeyTrac API is only available through an SSL-secured HTTPS connection. Unencrypted HTTP connections are not supported.

2) API access authentication

You may authenticate requests to the API using an 36 character long authentication token which needs to be included into your HTTP-Headers (learn more). This authentication token is required for every request you send to the API. You'll find this authentication token in your administration console. Please note that header fields are case sensitive. So the A of Authorization needs to be an uppercase character. If the authentication token is missing or invalid you will receive a 401 Unauthorized response.

HTTP-Header Name Example HTTP-Header Information
Authorization Authorization: a4c0dc53-e763-4ef3-bd19-cc92734e8691 This authentication token is required on every API request.

Authentication Example

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

API conventions

1) Parameter encoding

All API endpoints only accept parameters encoded as JSON (Learn more). To send data to the API, you need to set the content type to Content-Type: application/json for every transmission. Other or empty content types are not recognized and will be answered with an error. For perfect compatibility, please ensure that your web service is able to handle JSON data and add HTTP-Header Accept: application/json for all your requests.

2) Character encoding

All data transferred by the API is encoded and handled in UTF8. Therefore, all data sent to the web service needs to be encoded in UTF8.

3) Time and Date formats

Timestamps and dates are handled in UTC format. Timestamps sent with a time zone symbol will be converted to UTC.

Allowed Timestamp formats
2015-06-29 07:31:01 UTC
2015-06-29T07:31:01Z -> preferred format

Error conventions

1) Format information

The default error format is a simple JSON object with an error key and a corresponding error message:

{"error":"User not found"}

2) General API Errors

HTTP Status Error Message Error Description
400 {"error":"Attributes missing"} Sending invalid JSON data or wrong type of JSON to the API.
401 {"error":"Authentication token missing"} Accessing the API without an authentication token included into the HTTP Headers.
401 {"error":"Client unauthorized"} Accessing the API with an invalid authentication token.
403 {"error":"Account is not verified"} Accessing the API without verifying your account.
404 {"error":"Entity not found"} Trying to access unknown resources which do not exist.
500 {"error":"Unable to parse data"} The system is unable to parse the data you’ve send to an endpoint.

Create Users

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

1) User Creation Sequence Diagram

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.

2) Definition

A user in KeyTrac reflects an actual user of your web application. You can think of a user as a kind of an assignment unit where keystroke profiles are associated. These keystroke profiles can be divided in two types:

  • AnyText - Used for authentication based on arbitrary text
  • Password Hardening - Used for authentication based on the typing pattern of a password

To keep things simple, there is no need to enroll for both profile types. Users can be enrolled for either an AnyText profile, a Password Hardening profile or for both profile types. To create a new user, you need to call the /users endpoint of the API with a POST request. This causes the API system to create a new user and to respond the created unique identifier to your application.

3) Example Request

$ 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!

Show Users

1) Definition

To retrieve all users associated with your account, you need to call the /users endpoint of the API with a GET request. This causes the API system to respond a list of all users. Each user in this list is represented by its unique identifier, the creation timestamp and (when available) the timestamp of the last activity.

2) Example Request

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

[
  {"identifier":"8f5a2308-90b5-4afa-8847-ebf2b99f4082","created_at":"2016-03-24T11:45:24.812Z","last_activity":"2016-03-24 11:53:07.902Z"},
  {"identifier":"b26bdaef-2377-41db-9f73-b3bae1c6fb4a","created_at":"2016-03-24T11:45:09.603Z"}
]

3) Possible API Errors

HTTP Status Error Message
500 {"error":"Unable to compute user overview"}
The API system is unable to compute the list of users which is associated with your account.

Enroll/Train Users

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

1) Enrollment Sequence Diagram

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. Assemble the typing sample(s) and the KeyTrac user ID and send it to the KeyTrac API.
  4. The KeyTrac API creates a new user profile out of the given typing sample(s).

2) Definition

As a starting point, KeyTrac needs to learn the peculiarity of the keystroke dynamics of your users. This training is done using an enrollment process where the keyboard biometrics - previously recorded using the KeyTrac JavaScript Recorder (see the documentation) - are transformed in a user profile which is stored along the corresponding user in the KeyTrac system. To enroll a profile, you need to call the /anytext/enrol or the /password/enrol (depends on the KeyTrac variant you want to enroll for) endpoint of the API with a POST request and the JSON data attached to the request body.

3) Important Notes

For each of the two available KeyTrac types (AnyText or Password Hardening), a separate enrollment process is required. For example, when you enroll a user for the AnyText type this user is not automatically enrolled for the Password Hardening type and vice versa. If you want to enroll a profile for Password Hardening, all typing samples you want to use need to be recorded in the masked format. This ensures that no sensitive data is included in the sample. (Click for further information)

4) Enrollment Prerequisites

For each enrollment (AnyText or Password Hardening) you'll need at least the following data:

  • A user ID (represented by its 36 character long user identifier)
  • At least one fresh recording of keystroke dynamics, performed by the KeyTrac Recorder JavaScript

Both pieces of information are now used to build a JSON data structure which is required by the KeyTrac API system. The data below shows an example JSON structure used to enroll a profile. The data in the typing sample array are keystroke dynamics recorded by the KeyTrac Recorder JavaScript.

{
  "user_id":"826efc1d-78e5-4e69-b144-de090de6094b",
  "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",
    "firefox/38.0#m=0#2016-01-29 17:51:29|0dRSHIFT|280d84|42uRSHIFT"
  ]
}

5) The Enrollment Request

For simplicity, the schema of the JSON data structure used to enroll profiles remains always the same, only the API endpoint changes according to the KeyTrac variant you want to enroll.

5.1) Example Enrollment Request - AnyText

The API endpoint used for the AnyText enrollment: https://api.keytrac.net/anytext/enrol

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<YOUR AUTHENTICATION TOKEN>>" \
  -d '{"user_id":"<<USER ID FROM STEP [Create Users]>>","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}

5.2) Example Enrollment Request - Password Hardening

The API endpoint used for the Password Hardening enrollment: https://api.keytrac.net/password/enrol

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<YOUR AUTHENTICATION TOKEN>>" \
  -d '{"user_id":"<<USER ID FROM STEP [Create Users]>>","samples":[
    "firefox/38.0#m=0#2016-04-25 09:25:37|l=7|0dI0|72uI0|32dI1|72uI1|120dI2|120uI2|112dI3|64uI3|64dI4|112uI4|32dI5|96uI5|40dI6|88uI6",
    "firefox/38.0#m=0#2016-04-25 09:25:40|l=7|0dI0|56uI0|72dI1|64uI1|112dI2|128uI2|128dI3|56uI3|72dI4|72dI5|24uI4|80dI6|32uI5|48uI6"]}' \
  https://api.keytrac.net/password/enrol

{"OK":true}

6) Re-Enrollments of user profiles

If you re-enroll a user who is already enrolled for a KeyTrac version (AnyText or Password Hardening), the stored typing profile will be overwritten. This feature can be used to re-train the keystroke dynamics of an existing user. A re-enrollment is simply done by executing the enroll method again for an enrolled user.

7) Possible API Errors

HTTP Status Error Message
400 {"error":"Samples contain mixed device types"}
The submitted Samples originate from mixed devices (mobile/desktop).
400 {"error":"Insufficient number of unique samples submitted"}
The number of unique typing samples you’ve submitted is insufficient. Multiple duplicates oft yping samples are not allowed.
400 {"error":"Sample #1 is corrupted or format is not valid"}
Submitted sample no. 1 is corrupt or not in the format which KeyTrac requires.
400 {"error":"Unable to determine text length of sample"}
The API system is unable to determine the length of the text in the given sample.
400 {"error":"Combined text length of given samples are insufficient. The minimum text length of the combined samples is set to X characters. To change this setting, please log in to your KeyTrac Console - https://console.keytrac.net"}
The combined text length of all given samples doesn’t comply with your settings. Applies only to AnyText.
400 {"error":"Sample #1 is invalid and can’t be used with this type of enrollment/authentication"}
 Submitted sample no. 1 is not suitable for this type of enrollment/authentication. For password based authentications/enrollments, only samples in the masked format are allowed.
400 {"error":"Sample #1 does not contain a sample length"}
Submitted sample no. 1 does not contain a sample length (...
400 {"error":"Sample #1 does not contain any user inputs"}
Submitted sample no. 1 is “empty” and does not contain any user inputs.
400 {"error":"Sample size is ambiguous"}
One, or more, input samples have different input sizes. For Password Hardening, all samples must have the same input length. For instance, if the password of a user has a length of 10 characters, each sample must have a length of 10 characters.
400 {"error":"Insufficient number of submitted samples. The minimum sample count is set to X samples. To change this setting, please log in to your KeyTrac Console - https://console.keytrac.net"}
You have not submitted enough samples. This is a client-specific setting and can be changed in the KeyTrac Console website. This only applies to Password Hardening.
400 {"error":"Given samples are out of specification"}
You submitted samples that are out of specification, e.g. corrupted, too short or consist only of downkeys etc.
500 {"error":"Unable to enroll profile for user"}
The API system is unable to create a profile for the given user.

Authenticate Users

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

1) Authentication Sequence Diagram

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. Assemble the typing sample(s) and the KeyTrac user ID and send it to the KeyTrac API.
  4. KeyTrac API computes a matching-score of the given typing sample(s) compared to those in the stored user profile.
  5. Use the decision from KeyTrac to accept or reject the user's authentication attempt.

2) Definition

The authentication is similar to the enrollment shown above. You need to provide the identifier of the user that should be authenticated. The samples used for authentication must also be recoded using the KeyTrac Recorder JavaScript. To authenticate a user, you need to call the /anytext/authenticate or the /password/authenticate (depends on the KeyTrac variant you want to use) endpoint of the API with a POST request and the JSON data attached to the request body.

Once you try to authenticate a user against the KeyTrac web service, it 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.

If a user was successfully authenticated, the API system automatically updates the stored profile of the user in order to adapt to the changing keystroke dynamics of the user.

3) Important Notes

For using Password Hardening, all typing samples need to be recorded in the masked format. This ensures that no sensitive data is included in the sample. (Click for further information)

4) Authentication Prerequisites

For each authentication (AnyText or Password Hardening) you'll need at least the following data:

  • The 36 character long identifier for a user
  • The user specific, fresh recording of keystroke dynamics

Both pieces of information are now used to build a JSON data structure which is required to authenticate a user against the KeyTrac API system. The data below shows an example JSON structure used to authenticate a user. The data in the samples array is the keystroke dynamics recorded by the KeyTrac Recorder JavaScript.

{
  "user_id":"826efc1d-78e5-4e69-b144-de090de6094b",
  "samples":[
    "firefox/38.0#m=0#2016-01-29 18:50:51|0dRSHIFT|320d84|48uRSHIFT"
  ]
}

5) The Authentication Request

For simplicity, the schema of the JSON data structure used to authenticate users always remains the same, only the API endpoint changes according to the KeyTrac variant you want to use for authentication.

5.1) Example Authentication Request - AnyText

The API endpoint used for the AnyText authentication: https://api.keytrac.net/anytext/authenticate

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<YOUR AUTHENTICATION TOKEN>>" \
  -d '{"user_id":"<<USER ID FROM STEP [Create Users]>>","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}

5.2) Example Authentication Request - Password Hardening

The API endpoint used for the Password Hardening authentication: https://api.keytrac.net/password/authenticate

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<YOUR AUTHENTICATION TOKEN>>" \
  -d '{"user_id":"<<USER ID FROM STEP [Create Users]>>","samples":["firefox/38.0#m=0#2016-04-25 09:27:05|l=7|872dI0|56uI0|64dI1|72uI1|128dI2|104uI2|117dI3|43uI3|72dI4|104uI4|24dI5|72dI6|40uI5|40uI6"]}' \
  https://api.keytrac.net/password/authenticate

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

6) Possible API Errors

HTTP Status Error Message
400 {"error":"Samples contain mixed device types"}
The submitted Samples originate from mixed devices (mobile/desktop).
400 {"error":"Sample #1 is corrupted or format is not valid"}
Submitted sample no. 1 is corrupt or not in the format which KeyTrac requires.
400 {"error":"Unable to determine text length of sample"}
The API system is unable to determine the length of the text in the given sample.
400 {"error":"Sample #1 is invalid and can’t be used with this type of enrollment/authentication"}
 Submitted sample no. 1 is not suitable for this type of enrollment/authentication. For password based authentications/enrollments, only samples in the masked format are allowed.
400 {"error":"Sample #1 does not contain a sample length"}
Submitted sample no. 1 does not contain a sample length eg. l=12. Maybe the end user tried to manipulate the sample. This only applies to Password Hardening.
400 {"error":"Sample #1 does not contain any user inputs"}
Submitted sample no. 1 is “empty” and does not contain any user inputs.
400 {"error":"Sample size is ambiguous"}
One, or more, input samples have different input sizes. For Password Hardening all samples must have the same input length. For instance, if the password of a user has a length of 10 characters, each sample must have a length of 10 characters.
400 {"error":"Authentication rejected, mismatch of sample and profile size"}
The submitted sample(s) are incompatible with the stored profile. An error of this kind is raised when a user has a profile enrolled with a password length of 6 characters but the submitted sample(s) have a length of e.g. 10 characters. This happens for example if a user has changed his/her password but this change was not re- enrolled with KeyTrac. This only applies to Password Hardening.
400 {"error":"Insufficient number of submitted samples. The minimum sample count is set to X samples. To change this setting, please log in to your KeyTrac Console - https://console.keytrac.net"}
You have not submitted enough samples. This is a client-specific setting and can be changed in the KeyTrac Console website. This only applies to Password Hardening.
400 {"error":"Given samples are out of specification"}
You submitted samples that are out of specification, e.g. corrupted, too short or consist only of downkeys etc.
404 {"error":"User is not yet enrolled for this authentication type"}
The user you’ve tried to authenticate with this type (AnyText or Password Hardening) of KeyTrac authentication does not have a profile for this type of authentication.
500 {"error":"Unable to deserialize profile of user"}
The API system is not able to load a stored profile.
500 {"error":"Unable to adapt profile of user"}
The API system is not able to adapt a user’s profile using the new submitted typing behavior.
500 {"error":"Unable to authenticate user"}
The API system is not able to decide about the authenticity of the submitted samples for a technical reason.

Identify Users

Rule of thumb: Before you're able to identify users, they need to be enrolled first!

1) Identification Sequence Diagram

Identification 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. Assemble the typing sample(s), the number of desired results and send it to the KeyTrac API.
  4. KeyTrac API compares the submitted typing sample(s) with your the stored user profiles.
  5. Use the match-score from KeyTrac to get the identity of a user.

2) Definition

The identification of users is quite similar to the enrollment or the authentication shown above. But in contrast to both methods, only a typing sample and an optional limit setting, which controls the number of results, is required to build your request. As the identifcation is only available for AnyText, you need to call the /anytext/identify endpoint of the API with a POST request and the JSON data attached to the request body.

Once you try to identify a user with Keytrac web service, it compares the submitted typing sample against each stored profile of your users and stores the unique user identifier and the percentual match-score for the response to your backend. The KeyTrac API orders the result in descending order, which means that the best match is in the first place. The higher the score, the higher is the matching. The minimum score is 0. The maximum score is 100.

You have the freedom to decide, at what degree of match you want to identify a user as a particular user.

3) Important Notes

As the user identifcation is only availabe for AnyText, it's required to only pass typing samples in the unmasked format to the KeyTrac API system. (Click for further information)

4) Identification Prerequisites

For each identifcation you'll need at least the following data:

  • The user specific, fresh recording of keystroke dynamics
  • The optional limit setting to get a specific result length

Both pieces of information are now used to build a JSON data structure which is required for use with the KeyTrac API system. The data below shows an example JSON structure used to identify a user. The data in the samples array is the keystroke dynamics recorded by the KeyTrac Recorder JavaScript.

{
  "limit":3,
  "samples":[
    "firefox/38.0#m=0#2016-01-29 18:50:51|0dRSHIFT|320d84|48uRSHIFT"
  ]
}

5) The Identification Request

The API endpoint used for the AnyText identifcation: https://api.keytrac.net/anytext/identify

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<YOUR AUTHENTICATION TOKEN>>" \
  -d '{"limit":3,"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/identify

  [
    {"user_id":"50f675c1-ca50-4be0-9745-7ed7beae215a","score":99},
    {"user_id":"27834245-c960-49be-b801-adf97cff3b2c","score":27},
    {"user_id":"c75c2689-7a85-41fe-988c-c84196ec4a5a","score":3}
  ]

6) Possible API Errors

HTTP Status Error Message
400 {"error":"Samples contain mixed device types"}
The submitted Samples originate from mixed devices (mobile/desktop).
400 {"error":"Sample #1 is corrupted or format is not valid"}
Submitted sample no. 1 is corrupt or not in the format which KeyTrac requires.
400 {"error":"Sample #1 is invalid and can’t be used with this type of enrollment/authentication"}
 Submitted sample no. 1 is not suitable for this type of enrollment/authentication. Only samples in the unmasked format are allowed.
400 {"error":"Unable to determine text length of sample"}
The API system is unable to determine the length of the text in the given sample.
400 {"error":"Combined text length of given samples are insufficient. The minimum text length of the combined samples is set to X characters. To change this setting, please log in to your KeyTrac Console - https://console.keytrac.net"}
The combined text length of all given samples doesn’t comply with your settings. Applies only to AnyText.
400 {"error":"Given samples are out of specification"}
You submitted samples that are out of specification, e.g. corrupted, too short or consist only of downkeys etc.
404 {"error":"Unable to execute identification as no user is enrolled"}
An identification is not possible as no user is created or enrolled.
500 {"error":"Unable to identify user"}
The API system is not able to identify a user for a technical reason.

Delete Users

1) Definition

In order to delete users associated with your account, you need to call the /users/:user_identifier endpoint of the API in a DELETE request. The KeyTrac API tries to delete the user with the given identifier and responds with a success message.

2) Example user deletion request

$ curl -X DELETE -H "Authorization: <<YOUR AUTHENTICATION TOKEN>>" https://api.keytrac.net/users/8f5a2308-90b5-4afa-8847-ebf2b99f4082

{"OK":true}

3) Possible API Errors

HTTP Status Error Message Error Description
404 {"error":"User not found"} The user with the given identifer is not known by our API system.
500 {"error":"Unable to delete user"} The API system is unable to delete the user with the given identifer.

Show User Details

1) Definition

You can retrieve detailed information for all of your active users in our API system. The returned data includes some statistical data which you can utilize, for example to keep track of your users. To retrieve the user details, you need to call the /users/:user_identifier endpoint of the API with a GET request.

2) Example User Details Request

$ curl -H "Authorization: <<YOUR AUTHENTICATION TOKEN>>" https://api.keytrac.net/users/8f5a2308-90b5-4afa-8847-ebf2b99f4082

{
  "overview":{
    "enrolment_count":3,
    "authentication_count":232,
    "last_activity":"2015-06-29 07:31:01 UTC"
  },
  "method":{
    "anytext":{
      "last_activity":"2015-06-29 07:31:01 UTC",
    }, ...
  }
}

3) Possible API Errors

HTTP Status Error Message Error Description
404 {"error":"User not found"} The user is not known by our API system.
500 {"error":"Unable to calculate status"} The API system is unable to calculate the status for this user.

View Account status

1) Definition

You can query for account details which can be used with you application. To retrieve the account status, you need to call the /status endpoint of the API with a GET request.

2) Example Status Request

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

{
  "overview":{
    "users_created":1245,
    "enrolments":232,
    "authentications":51
  }
}

3) Supported query parameters

The /status endpoint supports form encoded query parameters which can be used to retrieve the status only for a given period of time.

The format of the submitted date needs to be YYYY-MM-DD. Other formats will be rejected.

Form encoded Parameter Value
from 2015-06-01
to 2015-12-01

2) Example Status Request with parameters

$ curl -H "Authorization: <<YOUR AUTHENTICATION TOKEN>>" https://api.keytrac.net/status?from=2015-06-01&to=2015-12-01

{
  "overview":{
    "users_created":1245,
    "enrolments":232,
    "authentications":51
  }
}

3) Possible API Errors

HTTP Status Error Message Error Description
400 {"error":"Only parameter [from] given. Require both parameters [from] and [to]"} It’s required to submit the [to] and [from] parameter in order to specify a valid time window.
400 {"error":"Only parameter [to] given. Require both parameters [from] and [to]"} It’s required to submit the [to] and [from] parameter in order to specify a valid time window.
400 {"error":"Format of parameter [from] is invalid: Only accept a format of [YYYY-MM-DD]"} You submitted a [from] date in a format which is invalid. The API requires a format of YYYY-MM-DD.
400 {"error":"Format of parameter [to] is invalid: Only accept a format of [YYYY-MM-DD]"} You submitted a [to] date in a format which is invalid. The API requires a format of YYYY-MM-DD.
400 {"error":"Date window is invalid: Parameter [to] must be greater than or equal to [from]"} The [to] parameter is below the [from] parameter. This doesn’t specify a valid date window.
500 {"error":"Unable to calculate status"} The status of your account can’t be calculated.