Authentication

Before you continue this part, make sure you understand the High-level architecture concept and Platform layout, and Authentication.
👉 Platform layout and Authentication
👉 Platform Architecture

For authentication, we use Auth2.0, and if you are going to use our API services, this part is important for you.

📘

When do I need JWT?

You need JWT only if you are going to use our API services.
In case if you use our platform for data collection and data processing only, and you distribute analytics and processed trips data via your own APIs, you can skip login and refresh JWT methods

Every time, when you create a deviceToken you will get a full set of items necessary to call APIs on behalf of the particular app use, including:

• DeviceToken
• JWT access token
• Refresh token

JWT access token has a limited lifetime, once it is expired, you can use refresh it using a dedicated API method and Refresh token.

APIs

📘

We don't aim to store any personal data

To create a DeviceToken for your app users, you have to call the API. No client data required, so, you can do it with an empty body.

However, you can add data like name, or your internal client ID for your own convenience. These fields are searchable in DataHub.

Create DeviceToken

To create a DeviceToken, you need instanceID and instanceKEY
👉 How to obtain InstanceID and InstanceKEY?

⚡ API Reference: Registration/create

{
  "DeviceToken": "",
  "AccessToken": {
    "Token": "string",
    "ExpiresIn": 0
  },
  "RefreshToken": "string"
}

📘

Store the DeviceToken in your Database

Once you received a DeviceToken, add it as a part of the user profile and store it in your database.

Log in

This method exists to obtain a JWT token. To make a call, please use the following details:

• InstanceID
• DeviceToken - as a user login
• InstanceKEY - as a user password

⚡ API Reference: Auth/Login

{
    "Result": {
        "DeviceToken": "",
        "AccessToken": {
            "Token": "",
            "ExpiresIn":
        },
        "RefreshToken": ""
    },
    "Status": 200,
    "Title": "",
    "Errors": []
}

Refresh JWT

Once your JWT expired, you will get an error 401, which means you have to refresh your current JWT token. To do that, you will require your current JWT and RefreshToken. If even one of them is missing, use the login method to get the actual JWT and refresh both tokens.

⚡ API Reference: Auth/RefreshToken

❤️ Best practice

There are two options on how you can create a DeviceToken / Register a user:

• Call the API from your mobile client (Mobile app) -> update the user profile with the DeviceToken on your back-end
• Call the API from your back-end and store the DeviceToken with the user profile

But for Login and Refresh token methods we encourage you to call the APIs from your mobile app only. It will allow you not to store and transfer data between the mobile app and your back end.