API Authorization

Get access to Telematics API

Authorization methods are located in User-service.

VERY IMPORTANT! Read it carefully:

Almost all responses contain DeviceToken, AccessToken and RefreshToken. We are currently in transition period of moving to a new platform. The existing platform already operates both with DeviceToken and AccessToken. We strongly recommend to store all three tokens to smoothly switch between platforms in the nearest future. After registration you will receive accessToken with JWT and refreshToken. Use JWT token for user's authorized requests. JWT token has a lifetime. After this period - it expires. When your JWT token is expired you should refresh your token. Here you can find information about how JWT works: https://jwt.io/introduction/ We will support the old platform till November 01, 2021 and keep inform all our clients about progress and required steps.

To get and manage data of individual user you need to authorize with user's deviceToken (or JWT token in some cases), user's InstanceID and InstanceKey. To get and manage consolidated and accumulated data of user groups and all other users separately from your back-end, you need to authorize in API as admin with API Authorization Credentials.

Authorization Types

API Services with authorization required	Authorization type	How to authorize in API
Individual user Statistics and Scorings API Individual user's Streaks	Authorize as User	InstanceID: User Group InstanceID Login: User DeviceToken Password: User Group InstanceKEY
User Management API Accumulated Statistics and Scorings API by a single user or a list of users in a single User Group (InstanceID) Consolidated Statistics and Scorings API by a single User Group (InstanceID) Accumulated Streaks by a single user or a list of users in a single User Group (InstanceID) Heartbeats (User(s) Permissions status)	Authorize as Admin with API Authorization Credentials	InstanceID: API InstanceID Login: API Login Password: API Password

API Authorization Credentials

Please, follow to your Management page in DataHub and generate API Authorization Credentials. Use provided credentials to get access to API. If you do not have access to Management page - please, ask your colleague with a Company Access to DataHub to provide you with these credentials.

API Authorization Credentials

Authorization

POST https://user.telematicssdk.com/v1/Auth/Login

The method allows to log into API and get access to sensitive information Authorization: Allow Anonymous

Headers

Name	Type	Description
InstanceID	string	User Group Instance ID or API Instance ID

Request Body

Name	Type	Description
LoginFields	string	User deviceToken or API Login
Password	string	User group Instance Key or API Password

200

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

Format of body request

Authorize as user

{
  "LoginFields": {deviceToken: "deviceToken"},
  "Password": "InstanceKEY"
}

Authorize as Admin with API Authorisation Credentials

Authorize as Admin with API Authorization Credentials
{
  "loginFields": {"Email":"[e-mail]"},
  "password": "Password"
}

curl Request:

Curl request

curl -X POST “
https://user.telematicssdk.com/v1/Auth/Login”
 -H “accept: /” -H “InstanceId: “String” -H “InstanceKey: “String” -H “Content-Type: application/json-patch+json” -d “{\“loginFields\“:{\“Email\“:\“[e-mail]\“},\“password\“:\“P@ssword\“}”

curl -X POST “https://user.telematicssdk.com/v1/Auth/Login” -H “accept: /” -H “InstanceId: “String” -H “InstanceKey: “String” -H “Content-Type: application/json-patch+json” -d “{\“loginFields\“:{\“Email\“:\“[e-mail]\“},\“password\“:\“P@ssword\“}”

Once you Log in and get credentials for further actions you have to be authorized. Please use Open Auth authorization.

Use "Authorization": "Bearer {Token}" // required in header for any method when authorization required. {Token} - the JWT token that you get in /v1/Auth/Login response method.

Please be informed, that the accesstoken expires every 2 hours. You have to update it every 2 hours using refresh token and method POST /v1/Auth/RefreshToken

We recommend keeping both AccessToken and Refresh token and set a schedule to refresh AccessToken to get seamless access to telematics platform, APIs and services

Authorization via Swagger

Swagger: https://user.telematicssdk.com/swagger/index.html

Login

Request

Please have API's InstanceID ready

Response

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

Autorization

Please add Bearer JWT to authorization form.

Make sure you used a proper format value.

Example of format

Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJiOTA5MDNkZi1iOWExLTQ3MzQtOWI1Yi02MDJkZGFiNmYwNmUiLCJqdGkiOiIzOGEyZmZmNi1kNmVkLTRjZGItOTRjMi1mOTk5NzIzYWUyYzMiLCJpYXQiOjE1ODQ0NTQ1MDcsIkFwcGxpY2F0aW9uSWQiOiIyMSIsIkRhdGFIdWJFbWFpbCI6ImFuZHJpeS50dXBjaGllbmtvQHJheGVsdGVsZW1hdGljcy5jb20iLCJJbnN0YW5jZUlkIjoiYThlN2I3M2YtNTA4Yi00OWNlLWFmNTItNGMwZTYwNzAxMTM2IiwiSW5zdGFuY2VLZXkiOiI2MjY5N2RiNi0xZjA1LTRlYmMtOTYzMC1iODg3MmIxNDJlMTIiLCJEZXZpY2VUb2tlbiI6ImI5MDkwM2RmLWI5YTEtNDczNC05YjViLTYwMmRkYWI2ZjA2ZSIsIkNvbXBhbnlJZCI6IjM5IiwiSXNEYXRhSHViVXNlciI6IlRydWUiLCJuYmYiOjE1ODQ0NTQ1MDcsImV4cCI6MTU4NTY2NDEwNywiaXNzIjoid2ViQXBpIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo1MTM3NCJ9.Cy2c_FowBg4Ts1aPsKILn5-uI8NcY9dVIB4w9f8a8rY

For security purpose the API will accept any value with no error message. However, if you use incorrect value, you won't be able to get information from sensitive API.