Fleet Clearance Tutorial (deprecated)

Create a Cloud App

In the "Build" and "Live data" tabs you will find your apps with configurations for retrieving vehicle data. 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 "Build" or "Live data" tab, click the big plus (+) button, select "Fleet" as the type and then select "Cloud App".
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. If it's an app for live vehicle data, 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.

In addition, you can find a section for generating MQTT certificates, which are needed to consume streaming data.

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 of a vehicle, go ahead and use the DELETE /fleets/vehicles/{vin} 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 or revoked depending on if the activation was still pending or not.

Subscribe to the fleet_clearance_changed webhook to receive a notification once the clearance state changes to any of the possible value approved, pending, revoking, revoked, rejected, canceled. Read more about the available notifications on the webhooks page.

Sandbox Virtual VINs

When you are working with our sandbox API, you can perform the fleet clearance using the VINs of any of your vehicle simulators. The clearance is always approved in a matter of seconds.

To provide additional testing opportunities, the sandbox API also accepts the following virtual VINs. What's special about these VINs is that they have a predetermined behaviour that allow you you to simulate different real-life scenarios. In addition, a virtual VIN may support REST API requests (pull) and MQTT streaming (push).

Streaming data via MQTT

If you are consuming data via the MQTT interface, the data will be put onto the stream automatically upon activation.

Here's an exampple of how MQTT data is consumed in the terminal.

    mosquitto_sub --disable-clean-session
  --cafile root.pem
  --cert certificate.pem.crt
  --key private.pem.key
  -h mqtt.high-mobility.com
  -p 8883
  -q 1
  -t 'live/level13/1FBBEDED80595912588FF4FF/#'
  -i '75374841-d7a5-4db7-b9b5-8a5f60eed79d'

The car simulator pushes each change that is done automatically to the MQTT broker.

Sandbox

When you are streaming simulator data, use the base URL sandbox.mqtt.high-mobility.com

Revoking clearance

It's possible to revoke a clearance at any point of time, which stops the data access immediately. This is especially important when a vehicle is being defleeted.

To do this, you just need to use the DELETE /fleets/vehicles/{vin} endpoint, which will update the status to revoking and then to revoked once the deactivation has completed. It's also possible to cancel the clearance procedure for vehicles that still are pending, which changes the state to canceled.

Getting an Access Token

In case you want to consume data via any of the pull-based APIs as well, it's possible to create an Access Token for it as well once the vehicle is in an approved state. 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.

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.

Revoking via Service Account API

In addition to the OAuth2 API, it is possisble to revoke an Access Token by providing the VIN to the DELETE /fleets/vehicles/{vin} endpoint, which is a convenience method.