Connect to the web API

TraX provides a web API based on REST design principles. To understand how the API works, and its evolution, see:

• TraX API reference - An OpenAPI document that describes operations, server URLs, and more.
• TraX API release log - Contains a chronologically ordered list of notable changes for each release of API.

Autentication & Authorization

Authentication and authorization are managed using the OAuth Resource Owner Password Credentials Grant flow, which is part of the OAuth 2.0 Authorization Framework RFC (section 4.3).

How the "OAuth resource owner password credentials grant flow" works

In short, the OAuth Resource Owner Password Credentials Grant flow works by requesting an access token from a token endpoint by passing account credentials in the request body. The access token mut be used in all subsequent API calls.

A successful request in the OAuth Resource Owner Password Credentials Grant flow returns a response payload that looks like this:

{
   "access_token": "<the key>", 
   "token_type": "bearer",
   "expires_in": 3599 
}

The access_token attribute holds the actual access token, and the expires_in attribute shows how long the access token is valid. When the access token has expired, a new one must be requested.

RECOMMENDED: Make the TSP API client code request a new access token at activation, and use the expires_in attribute divided by two (2) to schedule the request of a new access token to ensure a valid access token is always available.

Credentials required for API access will be shared in the early phases of the onboarding journey.

How to retrieve an access token

To retrieve an access token, construct a request like this:

Request header content-type: application/x-www-form-urlencoded

Request operation: POST [TraX web API token endpoint]/oauth/token

Request payload: 

grant_type=password&
client_id=<Client id>&
client_secret=<Client secret>&
username=<Client username>&
password=<Client password>

Using the access token in API requests

The Authorization header must be included in all API calls. Here's an API call example that receives a list of vehicles from the TraX vehicle store:

Request header: Authorization: Bearer [your access token]

Request operation: GET [TraX web API server URL]/trax/fleets/{fleetId}/vehicles

Response payload example:

{ "vehicles": [ 
   {
     "vehicleId": "740f410b-7f37-4dbc-9cc5-f7c160005dc7",
     "vin": "C25HA5R6LO5T2TE",
     "vehicleName": "SPACE TRUCK 8459",
     "brand": "Volvo",
     "model": "VHD 300 AF"
   }
 ]
}

Remember to change the fleetId in the URL to a fleet ID that has been onboarded to TraX by SKF.