Authentication

Before the X4Fleet REST API can be used, an active user with the role "Import Gateway" is required.

A Bearer Token can then be requested using a username and password. This token subsequently serves for authenticating further requests. Since this token expires within 90 days, it should be renewed regularly.

During technical framework upgrades it may happen that after a release all existing auth tokens are invalidated. To avoid suddenly being unable to send any requests, it is recommended to pre-authenticate before the actual requests (and thus reuse the token) and to automatically request a new auth token upon receiving error code 401 - Unauthorized. Important: build in a retry limitation to prevent an infinite loop.

Endpoint:

POST /token

Request

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

* For space reasons, the example has been split across multiple lines. cURL does not support line breaks!

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"
}

In addition to access_token, the accountId (account of the tenant/customer), mainGroupId (main group) and groupId (subgroup) will be used again later.

Common Error Messages

If the "Import Gateway" user is locked after failed login attempts, it can be unlocked again via the Admin.

To do so, in X4Fleet under Settings > Users > select "Import Gateway" user > press "Unlock login"

Common error messages are:

• {"error": "99" , "error_description": "LoginLockedOut"}
  --> Account locked due to failed login attempts
• {"error": "99", "error_description": "InvalidCredentials"}
  --> Wrong username or password
• Error Code 415 - Unsupported Media
  --> Wrong data type is used, e.g. "application/json" instead of "application/x-www-form-urlencoded"