Skip to content

Credentials API⚓︎

The Credentials API allows you to store and retrieve shared credentials for CloudConnect vehicles.

What are credentials?⚓︎

In most cases an authentication mechanism secures the telematics unit from being used by a malicious person. Oftentimes, the authentication mechanism dictates that certain credentials should be passed along in order to communicate with the telematics unit. The manufacturer of the telematics units or vehicle will provide you with these credentials.

The INVERS OneAPI needs these credentials in order to communicate with your telematics units. For example, whenever a command is sent to a NIU vehicle using the Vehicle Commands API, this command has to be translated and sent to the appropriate endpoint(s) of the NIU API. The INVERS OneAPI has to authenticate at this endpoint using your NIU credentials (client_id and client_secret).

The credentials for vehicles, that are connected through a cloud solution and therefore a third-party API, are typically shared by a group of vehicles. We call this kind of credentials shared credentials. Storing your shared credentials for the third-party API is a necessary step before you can add a CloudConnect vehicle to your fleet.

This API allows to store and manage shared credentials. You can store multiple credentials for the same third-party API, e.g. NIU, within your fleet. By doing so, you can use vehicles that require separate credentials for the same third-party API in one single OneAPI fleet. For example, NIU vehicles that are part of different NIU fleets can all be part of a single fleet within the INVERS OneAPI.

Warning

In some cases, mostly when a direct connection to the telematics unit via TCP is needed, the telematics unit has an individual password. This password needs to be transmitted when communicating with the telematics unit in order for it to do anything. We call this kind of credentials individual credentials. In this case, you don’t need to store any credentials through the Credentials API.

How to add new credentials⚓︎

New credentials can be added using the POST endpoint of this API (see API specification). A name can be specified when creating new credentials. This name has to be unique within your fleet and makes it easier for you to reference them later on, e.g. within FleetControl, when adding vehicles to your fleet that require them.

A unique identifier will be generated for all credentials. If you are adding vehicles to your fleet using the Vehicle Lifecycle API, this ID is required to tell the INVERS OneAPI how the vehicle can be accessed at the third-party API.

Info

You can only delete credentials if they are no longer required for any of the vehicles in your fleet.

How to update existing credentials⚓︎

The client_secret can be updated using the PATCH endpoint of this API (see API specification).

Info

You can only update the client_secret. Credentials with a different client_id are considered entirely new. Add them as described above in how to add new credentials.

Example⚓︎

The following examples shows how to store credentials. Follow instructions to get an access token first in order to retrieve a valid access token for the INVERS OneAPI.

1
2
3
4
5
6
7
8
9
curl -X POST \
    'https://api.invers.com/telematics-brands/❰brand❱/credentials' \ # (1)
    -H 'Authorization: Bearer ❰access_token❱' \ # (2)
    -H 'Content-Type: application/json' \
    -d '{
          "name": "NIU fleet Berlin",
          "client_id": "client1",
          "client_secret": "supersecret"
        }' # (3)
  1. Insert the right telematics brand for which you want to store credentials.
  2. Don’t forget to fill in your access token.
  3. Please provide your credentials for the third-party API and choose a name.

    You can also provide a name to easily reference the credentials later.

If the request has been successful, a JSON object is returned along with HTTP status code 201.

Here’s an example of what the response might look like:

1
2
3
4
5
{
  "id": "01F62857KMPG2NE2GK1W2N3QYS",
  "name": "NIU fleet Berlin",
  "client_id": "client1"
}
Back to top