OAuth 2.0 Client Credentials

Our OAuth 2.0 API with the client_credentials grant type allows you to create access tokens to manage your application resources. It's also possible for fleet solutions to use the REST API to retrieve vehicle data for any of their fleet vehicles. You can use the access tokens to authenticate with any of the following services:

We offer two different alternatives for creating an access token, both compliant with the OAuth2 standard. The first one is to use client credentials grant by authenticating with your Client ID and Client Secret. As a second option, you can use assertions for client authentication by generating private keys within our console and use your private key to authenticate using JWTs. You can choose the option that best fits your system design and software architecture.

Table of Contents

OAuth 2.0 with client_credentials grant

In order to get an access token, head to your application "OAUTH CLIENT" section in the console and copy the client_id and client_secret. Next you can make an API call to create a an access token:

curl --location 'https://sandbox.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"
}

The access token is valid for 5 minutes and can be used for any of the endpoints that are listed as the scope. The Token URI is listed in your application page in the console and differs between our sandbox and live data environments.

API Specification

You can see the endpoint specifications on the OpenAPI Reference page.

In this example you can see how the access token is included as the authorization bearer for retrieving the eligibility state of a vehicle.

curl --location 'https://sandbox.api.high-mobility.com//v1/eligibility' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJleHAiOjE2OTgwNzAwMDEsImlhdCI6MTY5ODA2OTcwMSwiaXNzIjoiaHR0cHM6Ly9zYW5kYm94LmFwaS5oaWdoLW1vYmlsaXR5LmNvbS92MS9hdXRoX3Rva2VucyIsInNjb3BlIjoiZmxlZXQ6Y2xlYXJhbmNlIHZlaGljbGU6ZWxpZ2liaWxpdHktY2hlY2sgdmVoaWNsZTpkYXRhIiwic3ViIjoiMjEwZmMyOTUtZDQ5OS00ZDgwLTk5MWUtZTQ3NTZlZDI3YTZmIiwidmVyIjoxfQ.2neMW6LioKvZYlbSTf-W4GwSHQmMr_8cyXfhyi4XJF-6F4HrvFNIsLlNUa93wp6BiJ_XEythR8DfWh0PrIaHrg' \
--data '{
  "vin": "2HM00000000000001",
  "brand": "sandbox"
}'
{
    "data_delivery": [
        "pull",
        "push"
    ],
    "eligible": true,
    "vin": "2HM00000000000001"
}

Authenticate with Private Key JWT

Private Key JWT Authentication supports client authentication using JWT assertions signed with asymmetric key pairs.

When to use?

While we recommand to use client_id and client_secret to authenticate, in some circumstances based on your requirements and internal policies you might want to use this approach.

The steps are as followed:

  1. Create a key-pair in the console for your application
  2. Sign a JWT with the required claims
  3. Call the /v1/access_tokens endpoint to get an access token. The parameter client_assertion_type must be included and set to urn:ietf:params:oauth:client-assertion-type:jwtbearer.
  4. Use the access_token value in the subsequent API calls

Private Key JWT Implementation Example

The following snippet shows an example of how a JWT is generated using the private key, and how the access token is used for authentication in a subsequent API request.

const jwt = require("jsonwebtoken")
const uuid4 = require('uuid4')
const request = require("request-promise");

var config = { client_id: "my-client-id", "inserted_at": "2020-06-22T09:38:09", "private_key": "-----BEGIN PRIVATE KEY-----\n....\n-----END PRIVATE KEY-----", "id": "f6c331c4-9271-4e3b-a8c4-6a2cacac6451" }


function get_jwt_token() {
  var payload = {
    ver: 2,
    iss: config.id,
    aud: "https://sandbox.api.high-mobility.com/v1",
    jti: uuid4(),
    iat: Math.round(Date.now() / 1000),
  }

  const private_key = Buffer.from(config.private_key, 'utf8')
  return jwt.sign(payload, private_key, { algorithm: 'ES256' })
}


async function get_client_credentials_access_token(client_assertion) {
  const response = await request.post({
    url: 'https://sandbox.api.high-mobility.com/v1/access_tokens',
    json: {
      client_assertion: client_assertion,
      grant_type: "client_credentials",
      "client_assertion_type": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    }
  })
  return response
}

async function get_eligibility_check(access_token) {
  const response = await request.post({
    url: 'https://sandbox.api.high-mobility.com//v1/eligibility',
    headers: {
      "Authorization": `Bearer ${access_token}`,
      "Content-Type": "application/json"
    },
    json: {
      vin: "2HM00000000000001",
      brand: "sandbox"
    },
  })

  return response
}

async function main() {
  try {
    const client_assertion = get_jwt_token()
    const access_token_response = await get_client_credentials_access_token(client_assertion)
    const eligibility_response = await get_eligibility_check(access_token_response.access_token)
    console.log(eligibility_response)
    console.log("Done")
  } catch (err) {
    console.error("Error in main:", err);
  }
}

main();

OpenAPI Specification

You can see all endpoint specifications on the OpenAPI Reference page.