The Datamotion Developer Hub

Welcome to the Datamotion developer hub. You'll find comprehensive guides and documentation to help you start working with our embedded services as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

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.

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

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 UserDataHub (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. 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) -> 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

Communication and Authentication Table


(see above)

Authentication method

Purpose of communication

1

DeviceToken

Using the DeviceToken and the SDK, your app can acсess basic driving statistics and trip data, or use user and vehicle services.
Additionally, the Telematics SDK has its own interface to get necessary analytics for user dashboard and trip analysis
:point-right: SDK in-build APIs*

2

User JWT Access token
:point-right: Get user JWT*

Using the User Access Token and the Datamotion API, your app can use a wide range of additional services such as Engagement, First Notification of Loss (FNOL), etc.
:point-right: API Services*

3

User JWT Access token
:point-right: Get user JWT

Using the User Access Token and the Datamotion API, your user can access and edit their own profile (name, email address, etc.)

5

DeviceToken through SNS (Amazon) and Azure Notifications (Microsoft)

Using the DeviceToken and the notification service of your platform (SNS or Azure Notifications), you can access data at any stage of data management cycle, as needed and on a user-by-user basis.
:point-right: how to grab data*

4

S3 bucket credentials

By adding your S3 Bucket Credentials to our UserDataHub, 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

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 tpyically 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 UserDataHub.
:point-right: [User management API]

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. the notification message contains trip credentials and URL to download JSON file.

Updated 13 days ago


Platform Layout and Authentication


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

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.