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.

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

KeyWhere is it required?
DeviceTokenTo enable SDK in the host app, and transfer data to the Platform
JWT access tokenTo call APIs
Refresh tokenTo refresh JWT access token

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.

API methods

Create DeviceToken


To create a DeviceToken, you need instanceID and instanceKEY
:point-right: How to obtain InstanceID and InstanceKEY?

:zap: 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

:zap: 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.

:zap: 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.

ConditionsActions
No DeviceTokenCreate a DeviceToken -> update user profile and store it next to the user in your database
JWT ExpiredRefresh JWT
No RefreshTokenLog in using DeviceToken as login and InstanceKEY as a password
No JWT tokenLog in using DeviceToken as login and InstanceKEY as a password