Set up the SDK login and API authentication

Introduction


In order to start using Telematics SDK, you have to create a DeviceTokenDeviceToken - It is a unique ID that is generated by Datamotion telematics platform and used by Telematics SDK as a user identifier. SDK connects all telematics data to the Devicetoken and transfer to Datamotion platform. Then the DeviceToken is used across all our APIs and services as a unique app user ID. for each app user. In plain English, you have to register all app users on Datamotion 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

Key

Where is it required?

DeviceToken

To enable SDK in the host app, and transfer data to the Platform

JWT access token

To call APIs

Refresh token

To refresh JWT access token

Every time, when you create a DeviceTokenDeviceToken - It is a unique ID that is generated by Datamotion telematics platform and used by Telematics SDK as a user identifier. SDK connects all telematics data to the Devicetoken and transfer to Datamotion platform. Then the DeviceToken is used across all our APIs and services as a unique app user ID. 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

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

Conditions

Actions

No DeviceToken

Create a DeviceToken -> update user profile and store it next to the user in your database

JWT Expired

Refresh JWT

No RefreshToken

Log in using DeviceToken as login and InstanceKEY as a password

No JWT token

Log in using DeviceToken as login and InstanceKEY as a password


Did this page help you?