INVERS shared mobility technology header mobile

Getting started

Authenticate API calls

All INVERS APIs use the OAuth 2.0 protocol for authentication and authorization. This tutorial shows how to get an access token which is needed when making API calls to the INVERS APIs. The examples show how to use the curl tool to get an access token and then make an authorized API call with it.

Further reading

For a more detailed description of the authentication process, feel free to read OAuth Authentication.

Step 1: Register a Client

In order to access the INVERS API from your application, you need an auth client for your application. Each client comes with its own OAuth 2.0 client credentials (client_id and client_secret). If you don’t have an auth client yet, please contact INVERS support in order to register a new client for you.

This step only has to be done once for your application.

Step 2: Obtain an Access Token

Let’s assume the following values for your OAuth 2.0 client credentials from step 1 (be sure to replace them with “your” values):

  • client_id: EXFL29#cl1
  • client_secret: eescrt8md3ntefkd...8m
Example call to obtain access token (curl)

Retrieve Token

curl -X POST \
  'https://api.invers.com/auth/oauth/token?grant_type=client_credentials' \
  -u 'EXFL29#cl1:eescrt8md3ntefkd...8m' \
  -H 'Content-Type: application/json'

The response from the authorization endpoint is a JSON object containing the access token that can be used for subsequent calls.

Response

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

The access token expires after 15 minutes (as indicated by the number of seconds in the expires_in property).

Step 3: Use the Access Token in API calls

Now it’s time for the first real API call: Let’s get a list of vehicles in your fleet from the API.

Example API call using access token (curl)

Be sure to replace with the access_token-value from step 2.

Example Request: Get list of vehicles

curl -X GET \
  https://api.invers.com/vehicles \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json'

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

You’ve done it! You can now use the access_token for any subsequent api calls in the next few minutes. In fact it is strongly recommended not to create a new access token for each api call but only if it is about to expire.

Consume Messages

For processing of operational and business events, the INVERS API supports push functionality via AMQP (Advanced Message Queue Protocol).​

We allow to consume messages using AMQP version 0.9.1.

To connect to the broker you need some configuration elements, which INVERS provides for you:​

  • Hostname of the AMQP broker
  • Connection port
  • Virtual host (to isolate “environments”, ensuring that your messages are only visible to you)
  • User name
  • Password
  • Queue name(s)​

​​Once you are connected to our AMQP Broker, your connection will remain alive. In default operation mode, new messages pushed to the queue are received by your system automatically.​

  • Messages published to the queue will be kept for one week. After this period the messages will expire.
  • Upon consumption your system has to acknowledge received messages. Acknowledged messages are removed from the queue. Unacknowledged consumed messages will be returned to the queue in the same order.​
  • For security reasons TSL is enforced.
  • Permissions will be set to basic.get and basic.consume only, so you cannot create new queues on the existing exchanges.​
  • It is recommended to set prefetch-count to 50.

See Code samples for simple examples of how to connect to our message queues in NodeJS, Java and .NET.

Here’s a code sample in C#:

string user = "f-FLT23-c-CNSM23A";
string pass = "<secret>";
string hostName = "api.invers.com";
int port = 5672;
string vhost = "fleet-FLT23";
string queueName = "VehicleStateReceived_v1-CNSM23A";
ConnectionFactory factory = new ConnectionFactory();
factory.Uri = new Uri($"amqps://{user}:{pass}@{hostName}:{port}/{vhost}");
IConnection conn = factory.CreateConnection();
IModel channel = conn.CreateModel();
var consumer = new EventingBasicConsumer(channel);
consumer.Received += (ch, ea) =>
  {
    var body = ea.Body;
    try
    {
      // ... process the message, with JsonDocument.Parse(body) 
      // or JsonSerializer.Deserialize(body)
    }catch(Exception e){
      e.Dump();
    }
    channel.BasicAck(ea.DeliveryTag, false);
  };
 
// Start consuming (consumer tag identifies the subscription
// when it has to be cancelled)
String consumerTag = channel.BasicConsume(queueName, false, consumer);