Platform Layout and Authentication
Our platform and your solution consist of multiple parts, with a variety of methods for communication 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.
- SDK call from your app to the Telematics SDK
- API call from your app to the Damoov Analytics API
- API call from your data back end to the Damoov Analytics API
- Data export from Damoov platform to your S3 bucket
- API call from your data back end to the Damoov User Management API
- API call from your admin back end to the Damoov Analytics API
- 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. ![]() ![]() |
2 | User JWT Access token![]() | 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.![]() |
3 | User JWT Access token![]() | 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. ![]() ![]() |
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. ![]() ![]() |
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. ![]() ![]() ![]() |
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.![]() |
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
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 |
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.
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 |
Updated about 1 month ago