OAuth 2.0 User Consent

Our OAuth 2.0 user consent flow allows a developer to delegate management of the end-user’s interaction with the relevant carmaker to High Mobility. Though the exact authorization flow differs from carmaker to carmaker, our platform ensures that these differences are transparent to the developer, which vastly reduces the effort needed to communicate with each of the carmarkers we support.

There are applications on the Samples page which implement the OAuth flow and use access tokens to query vehicle data.

Table of Contents

OAuth 2.0 Flow

A basic overview of the authorisation flow:

  1. Application redirects end-user to HIGH MOBILITY in the browser to begin the consent flow.
  2. End-user follows authorization sequence, approving requested permissions and verifying car ownership with carmaker
  3. End-user is redirected to app’s redirect_uri with authorization code
  4. App exchanges authorization code for an access token, which is used to call the API.

Ongoing usage: Use refresh tokens to obtain new access tokens

Note: The access token should be stored securely on the backend and care must be taken to ensure none of the credentials are exposed to the end-user.

The user's perspective

No matter how many car manufacturers we support, an application need only send a user to our authorisation URL, and HIGH MOBILITY will handle the rest of the consent process. To understand more about the user's experience during this process, please visit the following article on our blog. It details each of the steps the user in order to consent to the sharing of his or her car data.

Blog: User Consent and the Authorisation Process

What follows below are the steps and relevant technical aspects of the consent flow detailed in the above article.

High Mobility generates credentials upon account & app creation

When a developer registers for an account on High Mobility, a set of credentials are generated and associated with that account. Registered users can find the credentials in the OAuth tab of the My Settings page.

These are the parameters:

NameDescription
client_idThis is the public, unique identifier used to identify your account
client_secretThe client secret is private identifier used to authenticate your application when requesting an access token
auth_uriThis is the uri to which end-users are directed so they can authorize your application
token_uriThis is the uri where the authorization code is exchanged for an access token
url_scheme(for iOS & Android applications)
redirect_uri(registered by the app developer) The authorization server will only ever redirect end-users to this uri, which must be configured on the application’s server. The path will be appended with the authorization code when the authenticated user is redirected
app_idA unique serial number created for each of a developer's applications. This can be found on that particular app’s page under “Serial #”, and is the serial number of the application under which the token will be generated

Service sends end-user to Auth URI at High Mobility

The authorization flow is initiated when the service sends the user to the Auth URI

The typical authorization screen in an Oauth 2.0 flow—where the end-user chooses which data to share with an application—appears later in the flow. The page at High Mobility first asks the end-user to select the carmaker in question; the end-user is then led through that carmaker’s particular authentication and authorization process.

End-user is redirected to app’s redirect_uri with authorization code

Once the end-user has authorized access to the relevant data for his vehicle, he is redirected to the app’s redirect_uri, with either an authorization code—which will be exchanged for an access token in the next step—or an error, if for some reason the authorization sequence was not completed.

App exchanges authorization code for access token, which is used to call the API

If the query string code existed in the previous step, it means that the user has potentially approved your request; you can use this code to generate an access token. The service sends a POST request token_uri, sending the authorization code, client_id, client_secret, and redirect_uri in exchange for an access token.

With the access token, it is possible to get car data from the end-user’s vehicle.

Between the initial redirect and the issuing of the code, High Mobility handles the different authorization processes for each carmarker, which allows developers to focus on application development rather than keeping up with the various—and possibly evolving—authorization flows of each carmaker.

OAuth2 Technical Specifications

Server-Side Apps

This approach is useful for applications where the car owner signs up to your service and grants access from a browser on a desktop computer. The car owner trusts your service to take care of utilising the token on a specific device. This is useful for e.g. carsharing and delivery services.

Step 1 - Redirect end-user to HIGH MOBILITY in the browser to begin the consent flow

When requesting access to a car through OAuth, you should redirect user to the Auth URI using following parameters:

URLAuth URI
Request MethodGET redirect
Query string parameter KeyQuery string parameter Value
client_id(String) Client ID
redirect_uri(String) redirect_uri that you've entered in OAuth2 settings
app_id(String) the serial number of the application under which this token will be generated
state(Optional String) you may say any arbitrary data and you'll receive it when user is redirected back to your url
validity_start_date(Optional String) the start date and time from when the car access should be valid from. Formatted in ISO 8601 (e.g. "2017-08-21T13:20:20Z")
validity_end_date(Optional String) the end date and time until when the car access should be valid. Formatted in ISO 8601 (e.g. "2017-09-01T13:20:20Z")
brand(Optional String) the manufacturer brand that should be pre-selected. The value should be one of "bmw", "mini" or "mercedes-benz".
vin(Optional String) the 17-character Vehicle Identification Number that should be pre-filled.
locale(Optional String) the consent flow language that should be presented to the user. Currently the values "en-GB" for English and "de-DE" for German are supported.

Here is an example Auth URI, to which car-owners should be directed to start the consent flow:

https://sandbox.owner-panel.high-mobility.com/hm_cloud/o/bb8545d7-22bd-4bbc-b3e4-58a84a5328ac/oauth?app_id=50A018C136CF9BB7CE539590&client_id=e52b2864-7611-4f26-94e4-d13f7039f25d&redirect_uri=http%3A%2F%2Fhm-postman.local

Step 2 - end-user is redirected to app's redirect_uri with authorization code

After the car owner approves your application access, he/she gets redirected back to your configured redirect URL.

URLYour redirect URL
Request MethodGET redirect
Query string parameter KeyQuery string parameter Value
code(Optional String) if requested access was successfully granted to your app, this value is set. You can use this code for getting access token
error(Optional String) if requested access was not successful, this value is set
state(Optional String) if you passed state in the beginning of process, you'll receive it back here

The redirect_uri car owners will be directed back to will look something like this:

http://hm-postman.local/?code=20555e39-9a48-4808-8323-ca760f0f5261&state=&theme=

Step 3 - app exchanges authorization code for an access token, which is used to call the API

If the user is redirected back to you and the query string code exists, it means that user has potentially approved your request and you can use this code to generate an access token by calling Token URI.

For more information about exchanging the authorisation code for an access token, please see our OpenAPI Specification.

Here is an example request to exchange an authorization code for an access token:

curl --location --request POST 'https://sandbox.api.high-mobility.com/v1/bb8545d7-22bd-4bbc-b3e4-58a84a5328ac/oauth/access_tokens' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "client_id": "e52b2864-7611-4f26-94e4-d13f7039f25d",
    "client_secret": "rGGb45-awp0Q9X2yP3CxwhP8HhUY8uW1",
    "code": "20555e39-9a48-4808-8323-ca760f0f5261",
    "redirect_uri": "http://hm-postman.local",
    "grant_type": "authorization_code"
}'

{
    "token_type": "bearer",
    "status": "approved",
    "scope": "diagnostics.get.mileage diagnostics.get.fuel_level diagnostics.get.estimated_range diagnostics.get.battery_voltage diagnostics.get.fuel_volume diagnostics.get.engine_coolant_temperature diagnostics.get.battery_level cruise_control.get.cruise_control browser.set.url climate.set.hvac_state ignition.set.status",
    "refresh_token": "f5e6ca6e-e2cf-4130-9b3f-26727ca11f78",
    "expires_in": 3600,
    "access_token": "9290bc25-5514-4339-b6d1-c100af17d467",
    "authorization_id": "b378ac00-61e3-11ea-bc55-0242ac130003"
}

Ongoing usage: using refresh tokens to obtain new access tokens

When the access token expires, you will need a new access token. A new access token may be obtained through use of the refresh token. Please keep in mind that refresh token expire upon use; therefore, following requests will require the use of the new refresh toke, which is provided in response to this request.

For more information about using refresh tokens to obtain new access tokens, please see our OpenAPI Specification.

Here is an example request which sends a refresh token in exhange for a new access token and a new refresh token:

curl --location --request POST 'https://sandbox.api.high-mobility.com/v1/bb8545d7-22bd-4bbc-b3e4-58a84a5328ac/oauth/access_tokens' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--data-raw '{
    "client_id": "e52b2864-7611-4f26-94e4-d13f7039f25d",
    "client_secret": "rGGb45-awp0Q9X2yP3CxwhP8HhUY8uW1",
    "refresh_token": "f5e6ca6e-e2cf-4130-9b3f-26727ca11f78",
    "grant_type": "refresh_token"
}'            
{
    "token_type": "bearer",
    "status": "approved",
    "scope": "diagnostics.get.mileage diagnostics.get.fuel_level diagnostics.get.estimated_range diagnostics.get.battery_voltage diagnostics.get.fuel_volume diagnostics.get.engine_coolant_temperature diagnostics.get.battery_level cruise_control.get.cruise_control browser.set.url climate.set.hvac_state ignition.set.status",
    "refresh_token": "eebe7ecc-b9f6-4da7-906f-44d0975b27c4",
    "expires_in": 3600,
    "access_token": "dd789798-cf4c-4c7a-8461-e2270f9b2fe1",
    "authorization_id": "b378ac00-61e3-11ea-bc55-0242ac130003"
}

Mobile and Native Apps

The consent flow for Mobile and Native applications differs slightly from that of web-based or server-side applications. For more information, please visit one of the following links:

Android SDK
iOS SDK