Skip to content

Authenticate API calls⚓︎

All INVERS REST APIs use the OAuth 2.0 protocol for authentication and authorization. This tutorial shows how to get an access token which is needed to make calls to the INVERS APIs.

Note: While this guide provides an example of obtaining an access token using curl, it is important to mention that in a production environment, it is recommended to use established OAuth libraries tailored to your programming language of choice. These libraries are designed to handle the complexities of the OAuth 2.0 protocol, such as token refresh and security best practices. There usually is no need to implement the OAuth flow from scratch, unless you have a specific requirement that cannot be met by existing libraries.

For developers integrating with INVERS REST APIs using OpenID Connect, our OpenID configuration contains all the necessary endpoints and metadata for discovering our OAuth 2.0 and OpenID Connect capabilities. This metadata is useful for configuring OAuth 2.0 clients and can simplify the integration process. You can access our OpenID Connect configuration here: INVERS OpenID Configuration.

The examples show how to use curl to get an access token and then make an authorized API call with it.

Create a client⚓︎

In order to access the INVERS API from your application, you need a client for your application. If you do not have one, learn how to create a client. This only has to be done once for your application.

Authenticate⚓︎

Obtain an access token⚓︎

Let’s assume the following values for your OAuth 2.0 client credentials. Be sure to replace them with your values:

  • client_id: EXFL29#cl1
  • client_secret: eescrt8md3ntefkd…8m

Example (access token)⚓︎

Get an access token with your client’s credentials:

curl -X POST \
  'https://api.invers.com/auth/oauth/token?grant_type=client_credentials' \
  -u 'EXFL29#cl1:eescrt8md3ntefkd…8m' \ # (1)!
  -H 'Content-Type: application/json'
  1. Insert your combination of client_id and client_secret, separated by a : character.

The response from the authorization endpoint contains the access token.

{
  "access_token" : "eyJraWQiO…(truncated)…M2VhNtYWE3",
  "token_type" : "bearer",
  "expires_in" : 900
}

The access token can be used for subsequent calls to the REST APIs. It expires after 15 minutes as indicated by the number of seconds in the expires_in property.

Use access token in API calls⚓︎

Now it is time for the first real API call: Let’s get a list of vehicles in your fleet from the API. Be sure to replace ❰access_token❱ with the value in access_token from the previous step.

Example (API call)⚓︎

Get list of vehicles:

curl -X GET 'https://api.invers.com/vehicles' \ # (1)!
  -H 'Authorization: Bearer ❰access_token❱' \ # (2)!
  -H 'Content-Type: application/json'
  1. This example simply returns a list of your fleet’s vehicles. Passing the access_token works the same for all resources of the INVERS API.
  2. Insert your access_token as bearer.

If the request has been successful, a JSON object is returned along with HTTP status code 200. If there are vehicles in your fleet, the response contains a list of these vehicles.

Use the access token multiple times

Once you have the access token, be sure to use it for any subsequent calls in the next minutes. In other words: Do not get a new access token for every single API call.

It is recommended to wrap your REST API calls in a way that a new access token is automatically fetched if the existing token will expire in less than 2 minutes.