🔑 User Registration & API Integration

Introduction

To begin using the Telematics SDK, it's necessary to generate a new Telematics User Id (also known as DeviceToken) for each user of your app, or you can register an existing UUID on our platform. Simply put, every app user who will utilize telematics must be registered on the Damoov telematics platform. You should then store the DeviceToken in your database, linked to the app user's record. Alternatively, if you already use a user ID across your services, you can register this with Damoov as a CustomToken. The DeviceToken is then used as a key to activate the telematics SDK for each user. This integration involves both the generation of the DeviceToken and the 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

Methods for Backend integrations

API Method Create User

Python SDK Users

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.