API Dokumentation

Unsere RESTful API kann mit jeder Programmiersprache verwendet werden, die HTTP beherrscht.

Allgemeines

Mit der KeyTrac API steht Ihnen ein leistungsfähiger, RESTful Webservice zur Verfügung, der es Ihnen ermöglicht das Tippverhalten Ihrer Anwender für Authentifizierungszwecke nutzbar zu machen. Die KeyTrac API beinhaltet verschiedene Möglichkeiten um das Authentifizierungsverhalten Ihrer Anwender nachverfolgen und auszuwerten zu können.

API-Hostname

Unsere API ist unter https://api.keytrac.net verfügbar. Sämtliche Kommunikation mit dem API-Webservice ist nur über diesen Hostnamen möglich. Aus Sicherheitsgründen steht die KeyTrac API nur über HTTPS zur Verfügung. (Mehr erfahren)

HTTP Anfragen absenden

Zur besseren Veranschaulichung der Kommunikation mit der KeyTrac-API, kommt im weiteren Verlauf der Dokumentation der einfach zu nutzende und für viele Betriebssysteme verfügbare Konsolen HTTP-Client curl zum Einsatz. Da die KeyTrac-API nur wenig Konfiguration erfordert, sind nur folgende Optionen nötig:

Sicherheit und Authentifizierung

1) Übertragungssicherheit

Aus Gründen der Sicherheit ist die KeyTrac API nur über eine SSL-gesicherte HTTPS-Verbindung erreichbar. Unverschlüsselte HTTP-Verbindungen werden nicht unterstützt.

2) API-Zugriff und Art der Authentifizierung

Um mit der KeyTrac API kommunizieren zu können ist es notwendig, den 36 Zeichen langen API-Token als HTTP-Header (mehr erfahren) zu integrieren. Der API-Token muss in jeder Anfrage enthalten sein, die Sie an den Webservice senden.

Sie finden den Token in Ihrer Management Konsole. Bitte beachten Sie, dass bei den Schlüsselnamen im HTTP-Header zwischen Groß- und Kleinschreibung unterschieden wird. Deshalb ist es zwingend notwendig, dass das A von Authorization groß geschrieben wird. Sollten Sie den API-Token nicht oder fehlerhaft in Ihren HTTP-Header integriert haben, erhalten Sie einen 401 Unauthorized Antwort von der API.

Authentifizierungsbeispiel

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

API-Konvention

1) Parameterkodierung

Alle Endpoints der API arbeiten nur mit JSON enkodierten Parametern (Mehr erfahren). Um Daten mit der API austauschen zu können, müssen Sie den Content-Type bei jeder Übertragung auf den Content-Type: application/json setzen. Andere oder leere Content-Types werden nicht berücksichtigt und mit einer Fehlermeldung beantwortet. Für eine vollständige Kompatibilität stellen Sie bitte sicher, dass Ihr Webservice ebenfalls in der Lage ist mit JSON-Daten umzugehen. Dazu empfiehlt es sich neben dem Content-Type auch noch den Accept: application/json Header in alle Anfragen zu integrieren.

2) Zeichenkodierung

Allen Daten die Sie mit der API austauschen sind und werden in UTF8 enkodiert. Bitte stellen Sie ebenfalls sicher, dass Ihr Webservice mit UTF8 enkodierten Daten umgehen kann.

3) Zeit- and Datumsformate

Zeitstempel und Datumswerte werden im UTC Format behandelt. Alle Zeitstempel die Sie an die API senden werden in UTC konvertiert.

Fehlerkonventionen

1) Formatierungsinformation

Das Standard Fehler-Format ist ein einfaches JSON-Objekt, welches einen error Schlüssel und die jeweilige Fehlermeldung enthält.

{"error":"User not found"}

2) Globale API-Fehlermeldungen

Neue Benutzer erstellen

Faustregel: Für jeden Benutzer in Ihrer Anwendung müssen Sie auch in KeyTrac einen Benutzer erstellen.

1) Sequenz-Diagramm zur Benutzererstellung

1. Ein Benutzer registriert sich einen Zugang auf Ihrer Website.
2. Sie erzeugen nun für diesen Benutzer einen KeyTrac-Benutzer.
3. Die KeyTrac API antwortet mit einem Bezeichner, der mit den anderen Benutzerdaten gespeichert werden muss.

2) Definition

Ein Benutzer in KeyTrac spiegelt einen tatsächlichen Benutzer in Ihrer Webanwendung wider. Einen solchen KeyTrac-Benutzer können Sie sich als eine Art Speichereinheit vorstellen, mit der die jeweiligen Tippverhalten verbunden sind. Jeder dieser sog. KeyTrac-Benutzer besitzt dabei zwei unterschiedliche Profil-Typen:

• AnyText - Wird für die Authentifizierung mit beliebigen Texten verwendet
• Password Hardening - Wird für die Authentifizierung mittels der Passworteingabe genutzt

Damit es nicht zu kompliziert wird, müssen nicht beide Profil-Typen trainiert werden. So ist es problemlos möglich für einen Benutzer entweder nur das AnyText-Profil, nur das Passwort-Hardening-Profil oder eben beide Profil-Typen zu trainieren. Um einen neuen Benutzer in KeyTrac zu erzeugen, müssen Sie den /users Endpoint der API mittels einer POST Anfrage aufrufen. Das veranlasst die API einen neuen Benutzer zu erzeugen und den eindeutigen Bezeichner des Benutzers an Ihre Anwendung zurückzuliefern.

3) Beispiel-Anfrage

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

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

Die Benutzer-ID 8f5a2308-90b5-4afa-8847-ebf2b99f4082 wird exemplarisch in der gesamten Dokumentation verwendet und muss nicht einer tatsächlichen Benutzer-ID entsprechen!

Alle Benutzer anzeigen

1) Definition

Um alle Benutzer anzuzeigen, die Ihrem Zugang zugeordnet sind, müssen Sie den /users Endpoint der API mit Hilfe einer GET Anfrage aufrufen. Die KeyTrac API antwortet dann mit einer Liste aller Benutzer. Jeder Benutzer wird dabei mittels dessen eindeutigen Bezeichner, dem Erstelldatum und (wenn verfügbar) dem Zeitstempel der letzten Aktivität dargestellt.

2) Beispiel-Anfrage

$ curl -H "Authorization: <<IHR API-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) Mögliche API-Fehlermeldungen

Benutzer trainieren

Faustregel: Bevor Sie einen Benutzer trainieren können, müssen Sie diesen zunächst anlegen!

1) Sequenz-Diagramm zum Training

1. Ihre Website, wo der KeyTrac JavaScript Recorder integriert ist, wird geladen.
2. Beim Absenden des Formulars wird das aufgezeichnete Tippverhalten an Ihr Backend gesendet.
3. Kombinieren und senden Sie die Tippproben sowie die KeyTrac Benutzer-ID an die KeyTrac API.
4. Die KeyTrac API erzeugt aus den Tippproben ein neues Benutzerprofil.

2) Definition

Bevor KeyTrac Benutzer zuverlässig identifizieren kann, muss KeyTrac zunächst die Art und Weise erlernen wie ein Benutzer etwas auf der Tastatur tippt. Dieses Training kann beispielsweise während des normalen Registrierungsprozesses vorgenommen werden. Das Tippverhalten, welches vorher mit Hilfe des KeyTrac JavaScript Recorders (Dokumentation ansehen) aufgezeichnet wurde, wird hier in ein KeyTrac Benutzerprofil überführt, das dem jeweiligen Benutzer in KeyTrac zugeordnet und gespeichert wird. Sie erzeugen ein solches Profil indem Sie den /anytext/enrol oder den /password/enrol API-Endpoint (hängt von der Variante ab, die Sie verwenden möchten) mittels einer POST Anfrage aufrufen und so die JSON Daten an die API übermitteln.

3) Wichtige Informationen

Für jeden der beiden verfügbaren KeyTrac-Varianten (AnyText oder Password Hardening) ist ein unabhängiger Lernprozess notwendig. Trainieren Sie beispielsweise das AnyText-Profil eines Benutzers, wird nicht automatisch auch das Profil für Password Hardening trainiert und umgekehrt. Für das Training des Password Hardening Profils ist es zudem erforderlich, dass alle Tippproben im sog. maskierten Format aufgezeichnet werden. Dies stellt sicher, dass keine sensiblen sPasswortdaten in der Tippprobe enthalten ist. (Für mehr Informationen hier klicken)

4) Trainingsvoraussetzungen

Bei jedem Training (AnyText oder Password Hardening) werden folgende Daten benötigt:

• Der 36 Zeichen lange Benutzer-Bezeichner
• Min. eine aktuelle Aufnahme des Tippverhaltens, aufgezeichnet mit dem KeyTrac Recorder JavaScript

Diese beiden Informationen sind notwendig, um die JSON-Datenstruktur aufzubauen, welche die KeyTrac API erwartet. Das folgende Beispiel zeigt eine JSON-Datenstruktur die für das Training eines Benutzerprofiles verwendet wird. Die Daten im samples Array ist das vom KeyTrac Recorder JavaScript aufgezeichnete Tippverhalten.

{
  "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) Die Trainingsanfrage

Der Einfachheit halber wird das Schema der JSON-Datenstruktur für alle Trainingsanfragen beibehalten. Lediglich der API-Endpoint ändert sich entsprechend der Variante von KeyTrac die Sie trainieren möchten.

5.1) Beispiel-Anfrage - AnyText

Der API-Endpoint der für das Training der AnyText Variante verwendet wird lautet: https://api.keytrac.net/anytext/enrol

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<IHR API-TOKEN>>" \
  -d '{"user_id":"<<BENUTZER-ID VON SCHRITT [Neue Benutzer erstellen]>>","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) Beispiel-Anfrage - Password Hardening

Der API-Endpoint der für das Training der Password Hardening Variante verwendet wird lautet: https://api.keytrac.net/password/enrol

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<IHR API-TOKEN>>" \
  -d '{"user_id":"<<BENUTZER-ID VON SCHRITT [Neue Benutzer erstellen]>>","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) Erneutes Training von Benutzerprofilen

Wenn Sie bei einem bereits bestehenden Benutzerprofil, gleich ob AnyText oder Password Hardening, ein erneutes Training durchführen, wird das bisher gespeicherte Profil überschrieben. Dieses Verhalten kann dafür genutzt werden, um das Tippverhalten eines Benutzer erneut zu trainieren. Dazu müssen Sie lediglich eine neue Trainingsanfrage an den jeweiligen API-Endpoint senden.

7) Mögliche API Fehlermeldungen

Benutzer authentifizieren

Faustregel: Bevor Sie Benutzer authentifizieren können, müssen Sie sie erst trainieren!

1) Sequenz-Diagramm der Authentifizierung

1. Ihre Website, wo der KeyTrac JavaScript Recorder integriert ist, wird geladen.
2. Beim Absenden des Formulars wird das aufgezeichnete Tippverhalten an Ihr Backend gesendet.
3. Kombinieren und senden Sie die Tippproben sowie die KeyTrac Benutzer-ID an die KeyTrac API.
4. Die KeyTrac API erzeugt aus den Tippproben ein neues Benutzerprofil.
5. Verwenden Sie den Wahr/Falsch-Wert für die Entscheidung ob Sie der Authentifizierung vertrauen.

2) Definition

Die Authentifizierung von Benutzern verläuft ähnlich der bereits oben näher beschriebenen Trainingsphase. Auch bei der Authentifizierung muss der für den Benutzer einzigartige Bezeichner mit den Tippproben, welche vom KeyTrac JavaScript Recorder aufgezeichnet wurden, zusammengefasst als JSON-Daten an die KeyTrac-API übertragen werden. Dazu muss je nach KeyTrac-Variante der /anytext/authenticate oder der /password/authenticate Endpoint der API mittels einer POST Anfrage aufgerufen werden.

Jede Authentifizierung eines Benutzers gegenüber dem KeyTrac-Webservice wird entweder mit einem true Wert beantwortet, sollte die übertragene Tippprobe mit dem gespeicherten Benutzerprofil übereinstimmen. Wurde keine Übereinstimmung festgestellt, liefert die KeyTrac-API einen false Wert zurück. Zusätzlich zu diesem sog. boolschen Wert fügt die KeyTrac-API noch einen prozentualen Wert in die JSON-Antwort ein. Dieser Wert stellt die Genauigkeit der Übereinstimmung mit dem gespeicherten Benutzerprofil dar. Je höher der prozentuale Übereinstimmungswert, desto größer die Übereinstimmung. Der minimale Wert kann hier bei 0 und der maximale Wert bei 100 liegen. Alle Werte sind vom Typ Integer.

Wurde ein Benutzer erfolgreich authentifiziert, integriert die KeyTrac-API die neue Tippprobe automatisch in das gespeicherte Benutzerprofil.

3) Wichtige Informationen

Um Password Hardening verwenden zu können, müssen alle Tippproben im sog. maskierten Format aufgezeichnet werden. Dieses Format stellt sicher, dass keine sensiblen Passwortdaten in der Tippprobe enthalten sind. (Für mehr Informationen hier klicken)

4) Authentifizierungsvoraussetzungen

Bei jeder Authentifizierung (AnyText oder Password Hardening) werden folgenden Daten benötigt:

• Der 36 Zeichen lange Benutzer-Bezeichner
• Min. eine aktuelle Aufnahme des Tippverhaltens, aufgezeichnet mit dem KeyTrac Recorder JavaScript

Diese beiden Informationen sind notwendig, um die JSON-Datenstruktur aufzubauen, welche die KeyTrac API erwartet um eine Authentifizierung durchzuführen. Das folgende Beispiel zeigt eine JSON-Datenstruktur die zur Authentifizierung eines Benutzers notwendig ist. Die Daten im samples Array ist das vom KeyTrac Recorder JavaScript aufgezeichnete Tippverhalten.

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

5) Die Authentifizierungsanfrage

Der Einfachheit halber wird das Schema der JSON-Datenstruktur für alle Authentifizierungsanfragen beibehalten. Lediglich der API-Endpoint ändert sich entsprechend der Variante von KeyTrac die Sie authentifizieren möchten.

5.1) Beispiel-Anfrage - AnyText

Der API-Endpoint der für die Authentifizierung der AnyText Variante verwendet wird lautet: https://api.keytrac.net/anytext/authenticate

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<IHR API-TOKEN>>" \
  -d '{"user_id":"<<BENUTZER-ID VON SCHRITT [Neue Benutzer erstellen]>>","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) Beispiel-Anfrage - Password Hardening

Der API-Endpoint der für die Authentifizierung der Password Hardening Variante verwendet wird lautet: https://api.keytrac.net/password/authenticate

$ curl -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Authorization: <<IHR API-TOKEN>>" \
  -d '{"user_id":"<<BENUTZER-ID VON SCHRITT [Neue Benutzer erstellen]>>","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) Mögliche API Fehlermeldungen

Benutzer entfernen

1) Definition

Um Benutzer zu löschen, die Ihrem Zugang zugeordnet sind, müssen Sie den /users/:user_identifier Endpoint der API mit Hilfe einer DELETE Anfrage aufrufen. Die KeyTrac API versucht dann den Benutzer mit dem eindeutigen Bezeichner zu löschen und antwortet mit einer Erfolgsmeldung.

2) Beispiel Benutzer Lösch-Anfrage

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

{"OK":true}

3) Mögliche API-Fehlermeldungen

Benutzerdetails anzeigen

1) Definition

Sie können für alle aktiven Benutzer, die Ihrem Zugang zugeordnet sind, Details abrufen. Die von der KeyTrac-API zurückgelieferten Daten beinhalten viele statistische Informationen, die Sie beispielsweise für Auswertungszwecke verwenden können. Zur Abfrage der Informationen müssen Sie den /users/:user_identifier Endpoint der KeyTrac-API mittels einer GET Anfrage abrufen.

2) Beispielsanfrage für die Benutzerdetails-Anfrage

$ curl -H "Authorization: <<IHR API-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) Mögliche API Fehlermeldungen

Status des Zugangs anzeigen

1) Definition

Ähnlich des Status für Ihre aktiven Benutzer können Sie auch Informationen zum aktuellen Status Ihres Zugangs abfragen. Zur Abfrage der Informationen müssen Sie den /status Endpoint der KeyTrac-API mittels einer GET Anfrage abrufen.

2) Beispielsanfrage für den Zugangsstatus

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

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

3) Unterstützte Suchparameter

Neben der Anzeige des gesamten Status Ihres Zugangs können Sie den Zeitraum auf eine bestimmte Zeitperiode eingrenzen.

Das Format der Anfrageparameter muss im Format JJJJ-MM-DD vorliegen. Andere Formate werden nicht berücksichtigt.

2) Beispielsanfrage für den Zugangsstatus mit Parametern

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

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

3) Mögliche API Fehlermeldungen