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.
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)
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:
Optionsschalter | Bedeutung des Optionsschalters |
---|---|
-H |
Fügt einen HTTP-Header ein, der an die KeyTrac API gesendet wird (mehr erfahren) |
-d |
Sendet die angegebenen Daten an die KeyTrac API (mehr erfahren) |
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.
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.
HTTP-Header Name | Beispiel HTTP-Header | Information |
---|---|---|
Authorization |
Authorization: a4c0dc53-e763-4ef3-bd19-cc92734e8691 |
Der API-Token muss bei jeder API Anfrage enthalten sein. |
$ curl -H "Authorization: <<IHR API-TOKEN>>" https://api.keytrac.net/status
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.
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.
Zeitstempel und Datumswerte werden im UTC Format behandelt. Alle Zeitstempel die Sie an die API senden werden in UTC konvertiert.
Erlaubte Zeitstempel-Formate |
---|
2015-06-29 07:31:01 UTC |
2015-06-29T07:31:01Z -> bevorzugtes Format |
Das Standard Fehler-Format ist ein einfaches JSON-Objekt, welches einen error
Schlüssel und die jeweilige Fehlermeldung enthält.
{"error":"User not found"}
HTTP Status | Fehlermeldung | Bedeutung der Fehlermeldung |
---|---|---|
400 |
{"error":"Attributes missing"} |
Sie haben ungültige oder korrupte JSON-Daten an die API gesendet. |
401 |
{"error":"Authentication token missing"} |
Sie versuchen ohne einen API-Token auf die API zuzugreifen. |
401 |
{"error":"Client unauthorized"} |
Sie versuchen mit einem ungültigen API-Token auf die API zuzugreifen. |
403 |
{"error":"Account is not verified"} |
Sie versuchen auf die API zuzugreifen, haben aber Ihren Zugang noch nicht bestätigt. |
404 |
{"error":"Entity not found"} |
Sie versuchen auf eine unbekannte Ressource zuzugreifen. |
500 |
{"error":"Unable to parse data"} |
Die API kann die von Ihnen übergebenen Daten nicht auswerten. |
Faustregel: Für jeden Benutzer in Ihrer Anwendung müssen Sie auch in KeyTrac einen Benutzer erstellen.
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:
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.
$ 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!
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.
$ 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"}
]
HTTP Status | Fehlermeldung | Bedeutung der Fehlermeldung |
---|---|---|
500 |
{"error":"Unable to compute user overview"} |
Die API kann die Liste der Benutzer, die mit Ihrem Zugang verknüpft sind, nicht erstellen. |
Faustregel: Bevor Sie einen Benutzer trainieren können, müssen Sie diesen zunächst anlegen!
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.
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)
Bei jedem Training (AnyText oder Password Hardening) werden folgende Daten benötigt:
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"
]
}
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.
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}
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}
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.
HTTP Status | Fehlermeldung |
---|---|
400 |
{"error":"Samples contain mixed device types"} |
Die übermittelten Tippproben stammen von unterschiedlichen Geräten (Mobil/Desktop). | |
400 |
{"error":"Insufficient number of unique samples submitted"} |
Die Anzahl an einzigartigen Tippproben reichen nicht aus. Duplikate einer einzigen Tippprobe sind nicht zulässig. | |
400 |
{"error":"Sample #1 is corrupted or format is not valid"} |
Die erste der übermittelten Tippproben ist korrupt oder nicht im erwarteten Format. | |
400 |
{"error":"Unable to determine text length of sample"} |
Das API-System kann die Länge der Tippprobe nicht ermitteln. | |
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"} |
Die kombinierte Textlänge aller Tippproben liegt unterhalb der konfigurierten Textlänge. Gilt nur für AnyText. | |
400 |
{"error":"Sample #1 is invalid and can’t be used with this type of enrollment/authentication"} |
Die erste der übermittelten Tippproben kann nicht für diesen Trainings-/Authentifizierungstyp verwendet werden. Für die/das passwortbasierte Authentifizierung/Training sind nur Tippproben im maskierten Formaterlaubt. |
|
400 |
{"error":"Sample #1 does not contain a sample length"} |
Die erste der übermittelten Tippproben enthält keine Länge z.B. [l=12]. Möglicherweise hat der Anwender versucht die Tippprobe zu manipulieren. Gilt nur für Password Hardening. | |
400 |
{"error":"Sample #1 does not contain any user inputs"} |
Die erste der übermittelten Tippproben ist “leer" und beinhaltet keine Eingaben des Anwenders. | |
400 |
{"error":"Sample size is ambiguous"} |
Eine oder mehrere Tippproben weisen unterschiedliche Längen auf. Bei Password Hardening müssen alle Tippproben dieselbe Länge besitzen. Besteht das Passwort eines Anwenders beispielsweise aus 10 Zeichen, so muss auch die Tippprobe die Länge 10 besitzen. | |
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"} |
Sie haben zu wenige Tippproben übermittelt. Diese Einstellungen können Sie selbst in der Management-Konsole anpassen. Gilt nur für Password Hardening. | |
400 |
{"error":"Given samples are out of specification"} |
Sie haben Tippproben übermittelt, welche von KeyTrac nicht verarbeitet werden können, da sie z.B. korrupt, zu kurz sind etc. | |
500 |
{"error":"Unable to enroll profile for user"} |
Die KeyTrac API kann kein Benutzerprofil für den gewünschten Benutzer erstellen. |
Faustregel: Bevor Sie Benutzer authentifizieren können, müssen Sie sie erst trainieren!
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.
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)
Bei jeder Authentifizierung (AnyText oder Password Hardening) werden folgenden Daten benötigt:
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"
]
}
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.
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}
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}
HTTP Status | Fehlermeldung |
---|---|
400 |
{"error":"Samples contain mixed device types"} |
Die übermittelten Tippproben stammen von unterschiedlichen Geräten (Mobil/Desktop). | |
400 |
{"error":"Sample #1 is corrupted or format is not valid"} |
Die erste der übermittelten Tippproben ist korrupt oder nicht im erwarteten Format. | |
400 |
{"error":"Unable to determine text length of sample"} |
Das API-System kann die Länge der Tippprobe nicht ermitteln. | |
400 |
{"error":"Sample #1 is invalid and can’t be used with this type of enrollment/authentication"} |
Die erste der übermittelten Tippproben kann nicht für diesen Trainings-/Authentifizierungstyp verwendet werden. Für die/das passwortbasierte Authentifizierung/Training sind nur Tippproben im maskierten Formaterlaubt. |
|
400 |
{"error":"Sample #1 does not contain a sample length"} |
Die erste der übermittelten Tippproben enthält keine Länge z.B. l=12. Möglicherweise hat der Anwender versucht die Tippprobe zu manipulieren. Gilt nur für Password Hardening. | |
400 |
{"error":"Sample #1 does not contain any user inputs"} |
Die erste der übermittelten Tippproben ist “leer" und beinhaltet keine Eingaben des Anwenders. | |
400 |
{"error":"Sample size is ambiguous"} |
Eine oder mehrere Tippproben weisen unterschiedliche Längen auf. Bei Password Hardening müssen alle Tippproben dieselbe Länge besitzen. Besteht das Passwort eines Anwenders beispielsweise aus 10 Zeichen, so muss auch die Tippprobe die Länge 10 besitzen. | |
400 |
{"error":"Authentication rejected, mismatch of sample and profile size"} |
Die übermittelte(n) Tippprobe(n) sind nicht kompatibel mit dem gespeicherten Profil des Benutzers. Wurde etwa das Profil eines Benutzers mit einem 6 Zeichen langen Passwort trainiert, aber eine Authentifizierung mit einer z.B. 10 Zeichen langen Tippprobe versucht, erscheint dieser Fehler. Dies kommt z.B. dann vor, wenn der Benutzer sein Passwort geändert hat, jedoch vergessen wurde sein Profil mit dieser Änderung neu zu trainieren. Gilt nur für 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"} |
Sie haben zu wenige Tippproben übermittelt. Diese Einstellungen können Sie selbst in der Management-Konsole anpassen. Gilt nur für Password Hardening. | |
400 |
{"error":"Given samples are out of specification"} |
Sie haben Tippproben übermittelt, welche von KeyTrac nicht verarbeitet werden können, da sie z.B. korrupt, zu kurz sind etc. | |
404 |
{"error":"User is not yet enrolled for this authentication type"} |
Eine Authentifizierung des angegebenen Benutzers ist nicht möglich, da für den gewählten Authentifizierungs-Typ (AnyText oder Password Hardening) noch kein Profil trainiert wurde. | |
500 |
{"error":"Unable to deserialize profile of user"} |
Die KeyTrac-API kann das gespeicherte Profil nicht laden. | |
500 |
{"error":"Unable to adapt profile of user"} |
Die KeyTrac-API kann die Aktualisierung des Benutzerprofils nicht durchführen. | |
500 |
{"error":"Unable to authenticate user"} |
Die KeyTrac-API kann aus internen, technischen Gründen keine Authentifizierung durchführen. |
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.
$ curl -X DELETE -H "Authorization: <<IHR API-TOKEN>>" https://api.keytrac.net/users/8f5a2308-90b5-4afa-8847-ebf2b99f4082
{"OK":true}
HTTP Status | Fehlermeldung | Bedeutung der Fehlermeldung |
---|---|---|
404 |
{"error":"User not found"} |
Die API kann den Benutzer mit dem angegebenen Bezeichner nicht finden. |
500 |
{"error":"Unable to delete user"} |
Die API kann den Benutzer mit dem angegebenen Bezeichner nicht löschen. |
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.
$ 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",
}, ...
}
}
HTTP Status | Fehlermeldung | Bedeutung der Fehlermeldung |
---|---|---|
404 |
{"error":"User not found"} |
Der angegebene Benutzer wurde nicht gefunden. |
500 |
{"error":"Unable to calculate status"} |
Die KeyTrac-API kann den aktuellen Status des Benutzers nicht ermitteln. |
Ä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.
$ curl -H "Authorization: <<IHR API-TOKEN>>" https://api.keytrac.net/status
{
"overview":{
"users_created":1245,
"enrolments":232,
"authentications":51
}
}
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.
Form encoded Parameter | Wert |
---|---|
from |
2015-06-01 |
to |
2015-12-01 |
$ 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
}
}
HTTP Status | Fehlermeldung | Bedeutung der Fehlermeldung |
---|---|---|
400 |
{"error":"Only parameter [from] given. Require both parameters [from] and [to]"} |
Es muss sowohl ein gültiger [to] als auch ein gültiger [from] Parameter übergeben werden. |
400 |
{"error":"Only parameter [to] given. Require both parameters [from] and [to]"} |
Es muss sowohl ein gültiger [to] als auch ein gültiger [from] Parameter übergeben werden. |
400 |
{"error":"Format of parameter [from] is invalid: Only accept a format of [YYYY-MM-DD]"} |
Sie haben ein ungültiges [from] Datum übergeben. Die API erwartet das Format JJJJ-MM-DD. |
400 |
{"error":"Format of parameter [to] is invalid: Only accept a format of [YYYY-MM-DD]"} |
Sie haben ein ungültiges [to] Datum übergeben. Die API erwartet das Format JJJJ-MM-DD. |
400 |
{"error":"Date window is invalid: Parameter [to] must be greater than or equal to [from]"} |
Der [to] Parameter ist kleiner als der [from] Parameter. Das Zeitfenster ist damit ungültig. |
500 |
{"error":"Unable to calculate status"} |
Die KeyTrac-API kann den Status für Ihren Zugang nicht ermitteln. |