Set up the SDK login and API authentication

Introduction

In order to start using Telematics SDK, you have to create a DeviceToken for each app user. In plain English, you have to register all app users on Damoov telematics platform and store the DeviceToken in your database against the app user record. Then, you use the deviceToken as a Key to enable the telematics SDK for each app user. This integration step is about generating DeviceToken and Authentication process.

📘

one App user login has one DeviceToken

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

• Data workflow and categories of data

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 credentials in the response that are necessary to call APIs on behalf of the particular app use.

User credentials

• 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.

Framework for mobile apps

To make the integration easy and comfortable, we developed a framework and documentation to set up the SDK Log in and API Authentication.

• framework for iOS

• framework for Android

API methods

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), then update the user profile with the DeviceToken.
• Call the API from your back-end and store the DeviceToken with the user profile.

📘

Store DeviceToken in your Database

Once your created/ generated DeviceToken, pass it to your back-end and store it as a part of user profile.

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.