Fleet Clearance Tutorial

The Service Account API enables fleet owners to manage their fleet of vehicles and to retrieve Access Tokens for data consumption through the REST API or the Node.js SDK. If you are using Java, have a look at the Fleet SDK which simplifies the integration.

For carmakers that support fleet solutions, it's possible for fleet owners to get an Access Token without implementing the OAuth2 consent flow. This is due to the fact the the owner of the vehicle is not the driver, but the fleet owner. The Service Account API provides the necessary endpoints to:

  1. Add vehicle VINs to a production application
  2. Get the status of a vehicle, to see if it has been approved
  3. Get the Access Token for an approved vehicle

Production only

Note that fleet clearance is currently only possible for production applications. It is not supported yet by the car emulator.

Create a Production Cloud App

In the Production tab you will find your apps for retrieving data from our live environment. In the app details page you are going to set the permissions it requires and manage its credentials. Let's see how to create a new app.

  1. Go to the Production tab, click the big plus (+) button and select Cloud App. Enter a name and continue.
  2. Select the permissions that your app needs by clicking the "Select Permissions" button. Select the data points that you want to consume and hit "Save".
  3. Fill in all app information and click "Submit for review". Once done we will enable your application for live data access as soon as we have performed our app verification procedures. You will get notified as soon as it's done and it usually takes less than 48h.

Java Fleet SDK

If you are using Java in your backend, check out the Fleet SDK written in Kotlin.

You can already now get the credentials that you need to start the integration work. In the app details page you have these different sections in the menu to the left.

  1. The Client Certificate includes the credentials to use the REST API for data retrieval once you have an Access Token for a specific vehicle.
  2. The Service Account Keys section has the API keys that are necessary for the next steps of this tutorial. It is used to authenticate towards our fleet clearance API, which issues Access Tokens upon success.
  3. The OAuth2 API for revoking Access Tokens.

Helper image to find the credentials from the production cloud app menu:
Fleet SDK Credentials

Create and sign a JWT

With the app set up, it's time to use the Service Account API with the objective to get Access Tokens to be used for data retrieval using the REST API. Before using the fleet specific endpoints of the Service Account API, it's best to get familiar with the API and what's needed in order to get a JWT for each request. Read all about it in the Service Account Tutorial.

Getting clearance for a vehicle

Before data can be retrieved for a vehicle, it has to be cleared for access. The clearance procedure is different for each carmaker and should be considered an asynchronous process. It's possible to clear one or many vehicles at the same time, and this is done by passing in the Vehicle Identification Numbers (VINs).

Control Measure

For Mercedes-Benz vehicles, it's also necessary to pass in a control_measures object with the current vehicle odometer reading. This value is verified with the actual odometer reading during the clearance procedure.

Check out the Open API Specification to see the reference of the POST /fleets/vehicles and GET /fleets/vehicles endpoints.

You can subscribe to the fleet_clearance_changed webhook to receive a notification once the clearance state changes to approved, pending, revoked or rejected. Read more about the available notification on the Webhooks page.

# change AUTH TOKEN, VIN and ODOMETER
curl --location --request POST 'https://api.high-mobility.com/v1/fleets/vehicles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <AUTH TOKEN>' \
--data-raw '{"vehicles": [{"vin": "<VIN>", "brand": "mercedes-benz", "control_measures": {"odometer": {"value": "<ODOMETER>", "unit": "kilometers"}}}] }'

Getting an Access Token

Once a vehicle is in an approved state, it's possible to get an Access Token for it. The Access Token can be used with the Auto API REST API and the Node.js SDK in order to retrieve car data. The fleet Access Token endpoint of the Service Account API also returns a refresh token amongst other attributes, to be used to get new Access Tokens.

Check out the Open API Specification to see the reference of the POST /fleets/access_tokens endpoint.

# Change AUTH TOKEN and VIN
curl --location --request POST 'https://api.high-mobility.com/v1/fleets/access_tokens' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <AUTH TOKEN>' \
--data-raw '{
    "vin": "<VIN>"
}'
{
    "iss": "API Key uuid",
    "aud": "https://api.high-mobility.com/v1",
    "iat": "Current datetime in UNIX timestamp",
    "jti": "A random and unique UUIDv4",
    "ver": 1
}

Access Token lifecycle

Although the OAuth2 API is not used to get an Access Token, it is used to refresh the Access Token and to revoke access. It is therefore necessary to also implement OAuth2 endpoints to have a complete implementation.

Follow the OAuth2 Tutorial for details on how to implement the refresh and revoke functionality.