Platform Layout and Authentication

Our platform and your solution consist of multiple parts, with a variety of methods for communication and authentication.

Introduction

1796

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 methodPurpose of communication
1DeviceTokenUsing 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.
:point-right: Available SDK Methods
:point-right: API reference
2User JWT Access token
:point-right: 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.
:point-right: API Services
3User JWT Access token
:point-right: 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.)
4S3 bucket credentialsBy 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.
:point-right: how to export data to S3
:point-right: S3 reports
7Admin 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.

:point-right: Obtain Admin credentials
:point-right: Obtain Admin JWT
6Admin 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.
:point-right: User management API

:point-right: Obtain Admin credentials
:point-right: Obtain Admin JWT
8Notification service credentialsWe 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.

:point-right: 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

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

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

:zap: API Reference: User log in

Obtaining Admin JWT token

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

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

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