Platform Layout and Authentication

Introduction

Platform Communications Layout

Refer to the scheme above for the layout of the system, and to the table below for a decision of the authentication method purpose of the communication.

1. SDK call from your app to the Telematics SDK
2. API call from your app to the Damoov Analytics API
3. API call from your data back end to the Damoov Analytics API
4. Data export from Damoov platform to your S3 bucket
5. API call from your data back end to the Damoov User Management API
6. API call from your admin back end to the Damoov Analytics API
7. Data Export from Damoov platform to your server

Communication and Authentication Table

(see above)	Authentication method	Purpose of communication
1	DeviceToken	Using the DeviceToken, your app can access driving statistics, trip data, or use user and vehicle services. Additionally, the Telematics SDK has its own interface to register device tokens for your users. Available SDK Methods API reference
2	User JWT Access token Get user JWT*	Using the User Access Token and the Damoov API, your app can use a wide range of additional services such as Engagement, First Notification of Loss (FNOL), etc. API Services
3	User JWT Access token Get user JWT	Using the User Access Token and the Damoov API, your user can access and edit their own profile (name, email address, etc.)
4	S3 bucket credentials	By adding your S3 Bucket Credentials to our DataHub, you get daily data sets and statistics directly stored to your bucket. This is particularly well suited for low-frequency requests that your back-end will handle internally without making specific API calls, or for doing aggregate data analysis across many users. how to export data to S3 S3 reports
7	Admin JWT Access Token Analytics API	Using the Admin JWT Access Token, you can access data of other users through the Analytics API. This would typically be used for manager dashboard, company-wide access, etc. The systems using this access are typically server or cloud-based application, but it could also be used in a mobile app, for example if your fleet managers also have an app to view user data. Obtain Admin credentials Obtain Admin JWT
6	Admin JWT Access Token User Management API	Using the ADMIN JWT Access Token, you can manage users (create, delete, modify) through the API. This is particularly useful if you have a large user base and your own admin interface; alternatively, all basic user management could also be done through the DataHub. User management API Obtain Admin credentials Obtain Admin JWT
8	Notification service credentials	We provide capabilities to export data from Datamotion platform once it is received or processed. Please refer to Data management options. The service is provided via informing your server about new dataset or events. the notification message contains trip credentials and URL to download JSON file. Configuring notification service

Authentication Credentials

There are three main forms of authentication:

• A user-specific DeviceToken (GUID identifier)
• A user-specific Access Token (OAuth 2.0. JSON Web Token (JWT))
• An admin Access Token (OAuth 2.0. JSON Web Token (JWT))

Additionally, each admin account also has a device token for identification, and optionally login credentials for the DataHub (email/password).

📘

When do you 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

Log in

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

Obtaining User JWT token

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

API Reference: User log in

Obtaining Admin JWT token

• InstanceID
• Email - as an admin login
• Password - as an admin password
  Obtain admin login and password

API Reference: Admin log in

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

401 - Refresh JWT needed

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.