Authentifizierung

Bevor die REST API von X4fleet benutzt werden kann, wird ein aktiver Benutzer mit der Rolle “Import Gateway“ benötigt.

Folgend kann via Benutzername und Passwort ein Bearer Token beantragt werden. Dieser dient fortan als Token zur Authentifizierung weiterer Anfragen. Da dieser Token innert 90 Tagen abläuft, sollte dieser regelmässig erneuert werden.

Im Rahmen von technischen Framework-Upgrades kann es dazu kommen, dass nach einem Release alle bisherigen Auth-Token invalidiert werden. Um nicht plötzlich keine Anfragen mehr senden zu können wird empfohlen, die Authentifizierung den eigentlichen Requests vorzulagern (und somit den Token wiederzuverwenden) und bei einem Fehlercode 401 - Unauthorized automatisch einen neuen Auth-Token zu lösen. Wichtig, bauen Sie eine re-try Limitation ein, um eine Endlosschleife zu verhindern.

Endpunkt:

POST /token

Request

curl -X 'POST' \
  'https://gateway.x4fleet.com/token' \
  -H 'accept: */*' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'Username=________&Password=________'

* aus Platzgründen wurde das Beispiel auf mehrere Zeilen verteil. cURL unterstützt keine Zeilenumbrüche!

Response

{
  "access_token": "",
  "token_type": "bearer",
  "expires_in": ,
  "accountId": "",
  "mainGroupId": "",
  "groupId": "",
  "role": "ImportUser",
  "firstName": "Max",
  "lastName": "Mustermann",
  "emailAddress": "max@mustermann.ch",
  "languageId": "1",
  "activated": "true",
  ".issued": "Fri, 28 Mar 2025 13:23:42 GMT",
  ".expires": "Thu, 26 Jun 2025 13:23:42 GMT"
}

Neben access_token werden später accountId (Account des Mandant/Kunden), mainGroupId (Hauptgruppe) und groupId (Subgruppe) erneut verwendet.

Häufige Fehlermeldungen

Wenn der “Import Gateway“-Benutzer nach fehlerhaften Anmeldeversuchen gesperrt wird, kann dieser via Admin erneut freigeschaltet werden.

Dazu in X4fleet unter Einstellungen > Benutzer > “Import Gateway“-Benutzer an wählen > “Login freischalten“ drücken

Gängige Fehlermeldungen sind:

• {"error": "99" , "error_description": "LoginLockedOut"}
  --> Account wurde aufgrund Fehlversuchen gesperrt
• {"error": "99", "error_description": "InvalidCredentials"}
  --> Falscher Benutzername oder Passwort
• Error Code 415 - Unsupported Media
  --> es wird ein falscher Datentyp verwendet, zB. "application/json" anstatt "application/x-www-form-urlencoded"