Skip to content

Credentials⚓︎

The Credentials API allows you to store and retrieve shared credentials for vehicles using OEM Integrations.

What are credentials?⚓︎

Credentials are pieces of information commonly used to verify the identity of a user, e.g., the username and password you need to log into a website. Depending on the type of your telematics unit, the INVERS OneAPI may require similar credentials to interact with it. This allows the manufacturer of the telematics unit to secure it against malicious actors. If you need such credentials to interact with a telematics unit, they will be provided to you by the telematics unit manufacturer.

Info

Credentials are only required if you want to add NIU, Segway or Mercedes-Benz vehicles. When adding CloudBoxx vehicles, you do not need to provide credentials. INVERS associates your CloudBoxxes with your OneAPI fleet automatically.

For instance, when you send a command to a Mercedes-Benz vehicle using the Vehicle Commands API, a corresponding command in the Mercedes-Benz API will be executed. The Mercedes-Benz API will require the INVERS OneAPI to provide the correct 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 vehicle using OEM Integrations to your fleet.

The Credentials API allows you to store and manage shared credentials. You can store multiple credentials for the same third-party API, e.g., Mercedes-Benz, 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.

Warning

In some cases, mostly when a direct connection to the telematics unit via TCP is used, each individual telematics unit has its own 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 in FleetControl by navigating to Administration > Credentials. Alternatively, credentials can be added using the POST endpoint of the Credentials API. When creating new credentials, you should specify a name. This name has to be unique within your fleet and makes it easier for you to reference the credentials later on, for example 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 which credentials to use in order to access the vehicle at the third-party API.

Info

You can only delete credentials if they are no longer used by 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.

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": "Mercedes-Benz 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": "Mercedes-Benz fleet Berlin",
  "client_id": "client1"
}