.svg){kind=small}
Integrating High Mobility’s Vehicle Data API
Whether you aim to retrieve the current odometer reading from all your fleet vehicles or seek a snapshot of the latest vehicle health information, our connected car REST API stands as a popular choice for seamless integration. Nevertheless, the utilisation of our Service Account API for authentication has occasionally posed challenges in swiftly initiating data retrieval.
With the implementation of the new OAuth2 authentication and endpoint, High Mobility has streamlined the use of the REST API, enhancing the overall user experience. To facilitate a smoother transition for various integration approaches, we employed Postman to illustrate and emphasise the key changes introduced in our most recent release.
In order to start testing the new authorisation and retrieving vehicle data, we are recommending going through each of the following steps. Every underlying aspect will be explained in more detail both in the video of our 14th Open Dev Talk and this blog post.
- Review new Authorisation and Vehicle Data API changes on our platform (Applicable if you have already integrated with High Mobility)
- Fork Postman collection into your workspace
- Get and configure client credentials
- Get a new access token
- Fetch vehicle data using the Vehicle Data endpoint
What has changed with the new Authorisation and Vehicle Data API?
To activate vehicles and retrieve data, our customers were initially required to call the Service Account API to generate a short-lived token using a set of individual Service Account Keys. Once the vehicle is activated, another short-lived Vehicle Access Token could be requested through the Access Tokens endpoint. Subsequently, utilising this token, vehicle data values could be retrieved by calling individual endpoints or the vehicle status endpoint.
Our releases page outlines the newly facilitated workflow. In the first step, an access token needs to be requested using the High Mobility OAuth2 API. This access token can then be employed when calling various resources, including the Fleet Clearance API, the new Vehicle Data API endpoint, and the Vehicle Eligibility Check.
The Service Account Token API, Client Certificate Authentication for our Data API, and REST API v5 are now deprecated. These changes are also reflected in the High Mobility console. Upon logging in to the High Mobility platform and opening an existing data container, you will observe that Service Account Keys and Client Certificates are now marked as deprecated accordingly. Instead, the OAuth client credentials have been streamlined and refreshed, featuring the self-service generation of private keys for each respective client.
Finally, our Docs and Guides have been updated to provide detailed explanations of how the OAuth Authentication needs to be integrated.
Setting up Postman for the Vehicle Data API
At High Mobility, we have introduced a public Postman collection, accessible to anyone interested in accessing connected car data. To locate the collections for consumer services and fleet-related applications, simply perform a search for "High Mobility."
Our tutorial focuses initially on the Fleet Vehicle API, and an associated tutorial is listed on the Postman page as well. To commence, click the "Run in Postman" button and choose the workspace to fork and import the collection.
Before utilising the endpoints, it is essential to configure the Environment by using the OAuth Client ID and OAuth Client Secret. If you haven't created a data container yet, proceed to the High Mobility Sandbox or Live Data environment and create a new fleet app. Navigate to the OAuth Client section, copy the Client ID and Client Secret, and paste them into the corresponding fields in the Postman Fleet Env configuration. Ensure that you save the changes and verify that the appropriate Environment is selected in the upper right-hand corner of Postman.
Authorisation via OAuth2
Regardless if you like to manage vehicle clearance, check vehicle compatibility, or request actual vehicle data, the initial step involves requesting an OAuth2 Access Token.
In the Collections view, Postman provides an Authorisation tab that already showcases the pre-filled OAuth2 type and includes various configurations from the Environment, such as the Client ID and Client Secret.
Scroll down within the Authorisation tab and click on "Get New Access Token" to initiate the authentication process. After completing the authentication, you have the option to select "Hit use token" to automatically apply the Token for subsequent requests.
Managing fleet vehicle activation and fetching live data using the Vehicle Data API
Vehicles can be added using the Add Vehicle POST request listed in the Vehicle Management folder of the Fleet Vehicle API collection. When utilising the High Mobility sandbox, virtual cars are accessible for testing vehicle activation and data transmission.
To add a virtual car, navigate to the Simulation Studio on the High Mobility console and either reuse an existing simulator or create a new one. When launching and initialising the simulator, its corresponding Vehicle Identification Number (VIN) will be displayed as the top entry in the console below the main view.
Copy the VIN and paste it into the corresponding field of the message body in Postman to add the vehicle using the vehicle clearance API. Regardless of the selected Scene in the simulator, the associated brand must always be set to "sandbox" when working in the test environment.
After hitting "send," the car activation process will initially enter the pending state, which is also reflected in the API response. When using the "GET Vehicle" endpoint with the VIN as a Path Variable, you will be able to see the status change to approved, as simulated cars are activated automatically after a few seconds.
The Vehicle Data API is our new endpoint, serving as the central and single API to fetch data based on the permissions configured in the corresponding app container. In Postman, the Vehicle Status can be requested by setting the VIN as a Path Variable and hitting "Send." The response highlights all data values currently set in the corresponding simulator or, alternatively, the latest known real car values when using the Live Data environment. Each data value comes with a timestamp that provides more information about the point in time the value was generated.
Authorisation, consent and live data retrieval from privately-owned cars
If you intend to build and test a service associated with privately-owned vehicles, the same approach will work. First, import the Driver API to your local workspace and configure the Environment by copying the Client ID and Client Secret from a corresponding data container and saving changes.
To respect the integrated consent journey, Auth URI, Token URI will be pre-filled in the Driver Environment setup. Add "https://localhost" to the Redirect URI to enable a successful callback to Postman and apply the Driver Environment in the top right corner of Postman. If you have not worked with High Mobility's consent flow yet, you may want to review this Open Dev Talk.
When you hit the "Get new access Token" button in the Authorisation tab, a new popup window will appear, featuring the Driver user journey where users can review data permissions for respective cars or simulators. As soon as the user authorises access, the Auth Token can be utilised for the Vehicle Status API.
-------------------------------
High Mobility Open Dev Talks
At High Mobility, we are passionate about new technology. We offer free open source tools and developer friendly documentation for any projects to be integrated smoothly. More than 800 developers and product managers have already signed up for our moderated community platform and we are hosting connected car competitions for your innovative, connected car ideas. Join our community on Slack
