Service Account API Tutorial (deprecated)

The Service Account API authentication has been replaced by OAuth2. Head to the OAuth2 Client Credentials page for full details.

The Service Account API provides functionality related to your platform account. The usage is intended from your own cloud infrastructure and the API should not be used from front-end applications.

The Service Account API can today be used for:

  • Doing Vehicle Identification Number (VIN) lookups to see if a vehicle is capable of providing telematics data.
  • Adding and removing fleet vehicles and getting access tokens for cleared vehicles.
  • Managing Device Certificates. Retrieving the certificates is necessary when the HMKit iOS or Android SDK is being used in native smartphone applications.

Table of Contents

Once the administrator of your team creates an API key on the team settings page, a cryptographic key-pair is generated according to the JSON Web Token (JWT) standard. The JWT has to always be exchanged for an auth token in order to make requests to any of the functional endpoints.

Here's an overview of the steps:

Include the key-pair information in your back-end system. You can use your preferred JWT library.
Create an auth token per the example below.
Use auth token for all endpoints, e.g. Device Certificate creation or VIN lookup.

Endpoint URL

Note that the base URL is https://sandbox.api.high-mobility.com/v1 when working with the car emulators and https://api.high-mobility.com/v1 for cars in production mode.

How to create and sign a JWT

The JWT must contain the following claims:

Parameters

iss

The UUID of the API key

aud

Fixed string: https://api.high-mobility.com/v1. This is used to ensure that the JWT was meant to be used for our REST API

iat

The current datetime, formatted in the Unix timestamp format. This is used to minimize the possibilities of a replay attack, so that a JWT created in the past cannot be reused. Currently a tolerance of 30 seconds is used to account for any clock skew between our servers and the back end servers, but it can be changed, probably shortened in the future. Example value: 1502121268

jti

An unique identifier in the UUID format of the JWT itself to ensure a JWT can be used only once.

ver

The version of the JWT. Currently fixed value 1.

Discussion

After the JWT is created it must be signed with the private key returned in the Console, using the ES 256 algorithm. A list of libraries in various languages able to perform this can be found on the JSON Web Token official page.

Example

{
  "iss": "API Key uuid",
  "aud": "https://sandbox.api.high-mobility.com/v1",
  "iat": "Current datetime in UNIX timestamp",
  "jti": "A random and unique UUIDv4",
  "ver": 2
}

Implementation example

This is a full example for getting an auth token. For more languages, check out the examples repo on GitHub.

const jwt = require("jsonwebtoken")
const uuid4 = require('uuid4')
const request = require('request')

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

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

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

request.post({
    url: 'https://sandbox.api.high-mobility.com/v1/auth_tokens',
    formData: {assertion: jwtToken}
},
(error, response, body) => {
console.log('error:', error)
console.log('statusCode:', response && response.statusCode)
console.log('body:', body)
})

Use the access token which was obtained via /v1/auth_tokens endpoint as Bearer in other API calls

Example

curl -X POST 'https://sandbox.api.high-mobility.com/v1/auth_tokens' \
--header 'Content-Type: application/json' \
--data-raw '{"assertion":"eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJodHRwczovL3NhbmRib3guYXBpLmhpZ2gtbW9iaWxpdHkuY29tL3YxIiwiaWF0IjoxNjY5ODg1OTQzLCJpc3MiOiI1MzI2OWUyZS00ZjI3LTRjMGEtOTYyOS1jNjQ2ZmE0OGFhYjIiLCJqdGkiOiJmOGVmZjMzYS05YjdiLTQ4NWItYTdmOC01MDEyZjBhZmUyYTIiLCJ2ZXIiOjF9.O4wdgxUpzTMhyioLPMOCrLQUXNE0QwqLDYMaOk8wtElMvtMSPcbC_KqQB3hF0nnq20pvumyC5xxuhDd2MVm7Jw"}'
{
  "auth_token":"eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI8YXBwbGljYXRpb25fdXVpZD4iLCJpc3MiOiJodHRwczovL3NhbmRib3gtYmV0YS5hcGkuaGlnaC1tb2JpbGl0eS5jb20vdjEvYXV0aF90b2tlbnMiLCJleHAiOjE1MTYyMzkwMjJ9.heA5dvzL0Qe6C89lRRAB2_7QqQsYoaPcjlJuOqL320M",
  "valid_from":"2022-12-01T09:08:14",
  "valid_until":"2022-12-01T09:13:14"
}


curl 'https://sandbox.api.high-mobility.com/v1/fleets/vehicles' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiI8YXBwbGljYXRpb25fdXVpZD4iLCJpc3MiOiJodHRwczovL3NhbmRib3gtYmV0YS5hcGkuaGlnaC1tb2JpbGl0eS5jb20vdjEvYXV0aF90b2tlbnMiLCJleHAiOjE1MTYyMzkwMjJ9.heA5dvzL0Qe6C89lRRAB2_7QqQsYoaPcjlJuOqL320M'
[
  {
    "brand":"sandbox",
    "changelog":[{"status":"pending","timestamp":"2022-10-21T19:03:06"}],
    "status":"pending",
    "vin":"1HMSJBPPO6X2VVVP5"
  }
]