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 an Access Token for an approved vehicle
  4. Refresh and revoke an Access Token using the OAuth2 API

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 refreshing and 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.

Additional resources:

  • Check out the Open API Specification to see the reference of the POST /fleets/vehicles and GET /fleets/vehicles endpoints.
  • See the Activation Process guide for a detailed description of what happens under the hood during the clearance.

If you want to cancel the clearance process of a vehicle that still is pending, you can use the POST /fleets/{vin}/cancel_activation endpoint. Similarly to when adding a new vehicle for clearance, this endpoint is asynchronous. Once the request has been processed the vehicle will be set to canceled.

Subscribe to the fleet_clearance_changed webhook to receive a notification once the clearance state changes to any of the possible value approved, pending, revoked, rejected or canceled. Read more about the available notifications 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 create an Access Token for it. The Access Token can be used with the Auto API REST API, GraphQL API and the Node.js SDK in order to retrieve car data. The fleet Access Token endpoint also returns a refresh token amongst other attributes, to be used to refresh the Access Token as it expires.

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

Important

This endpoint for creating an Access Token is meant for one-time use. The OAuth2 API has to be used to get new Access Tokens as described in the last step of this guide.

# 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 refresh and revoke

Although the OAuth2 API is not used to create the first 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.

Check out the Open API Specification to see the references of the POST /access_tokens and DELETE /access_tokens endpoints.

You will find your OAuth2 credentials in your production cloud app menu (highlight number 3):
Fleet SDK Credentials