Fleet Clearance Tutorial

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.

Get an Access Token

With the app set up, it's time to use the Fleet Clearance API to add a vehicle and to retrieve data from it. To authenticate with any of the endpoints, you first have to create an OAuth2 Access Token.

1. Go to the "OAuth" tab in your app view
2. Note the Auth URI and store your Client ID and Client Secret securely
3. Use your credentials to to create an Access Token with the client_credentials grant:

curl --location 'https://api.high-mobility.com/v1/access_tokens' \
--header 'Content-Type: application/json' \
--data '{"client_id": "a92cf969-e8ff-4ad4-a45f-42930edde12d", "client_secret": "xfVxR6xnlbeVHXkQatRx4FmxSJxFR0-M", "grant_type": "client_credentials"}'
{
    "access_token": "eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTgwNzAwMDEsImlhdCI6MTY5ODA2OTcwMSwiaXNzIjoiaHR0cHM6Ly9zYW5kYm94LmFwaS5oaWdoLW1vYmlsaXR5LmNvbS92MS9hdXRoX3Rva2VucyIsInNjb3BlIjoiZmxlZXQ6Y2xlYXJhbmNlIHZlaGljbGU6ZWxpZ2liaWxpdHktY2hlY2sgdmVoaWNsZTpkYXRhIiwic3ViIjoiMjEwZmMyOTUtZDQ5OS00ZDgwLTk5MWUtZTQ3NTZlZDI3YTZmIiwidmVyIjoxfQ.2neMW6LioKvZYlbSTf-W4GwSHQmMr_8cyXfhyi4XJF-6F4HrvFNIsLlNUa93wp6BiJ_XEythR8DfWh0PrIaHrg",
    "expires_in": 300,
    "scope": "fleet:clearance vehicle:eligibility-check vehicle:data",
    "token_type": "bearer"
}

See the authentication tutorial for OAuth2 Client Credentials to get the full details and integration options.

Endpoint URL

Note that the API base URL is https://sandbox.api.high-mobility.com/v1 when working with the simulators and https://api.high-mobility.com/v1 for live vehicle data.

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).

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, revoked, rejected, canceled. Read more about the available notifications on the webhooks page.

Using tags

It is possible to store additional metadata together with each individual VIN clearance by using tags. Tags are key/value objects that you can use to store specific information such as:

• Identifiers that reference your internal database records
• Categorisation for your use-cases
• Segmentation for sub-fleets

While tags are genererally optional and intended for your own convenience, we do require the tag vw-group-customer-name to be passed in for Volkswagen Group brands: Volkswagen, Volkswagen Commercial Vehicles, Audi, Skoda, SEAT and CUPRA. This tag should hold the fleet operator business name, which we associate with the specific VIN activation. In case you are a fleet operator or always activate VINs for a specific fleet operator, you can ask our support team to configure a specific business name, thus omitting the need to pass in vw-group-customer-name as a tag.

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.

Pulling Vehicle Data

In case you want to pull data via our REST API, you can use the Access Token to authenticate with the Vehicle Data API once the vehicle is in an approved state.

curl --location 'https://api.high-mobility.com//v1/vehicle-data/autoapi-13/<vin>' \
--header 'Authorization: Bearer <ACCESS TOKEN>'

More Information

If you have any questions, please contact us on Slack or get in touch with our support.