Device API access

Device MQTT communication covers most of the operations required by the device.
In certain cases, the device needs to perform actions that are not covered by BioT MQTT support.
In these cases, the device can make RESTful HTTPS calls.
The full API documentation can be found here.

To make API calls, the device needs to obtain a JWT authentication token.
To obtain a token, the device needs to subscribe to the following topic during device initialization:

<clientId>/to-device/token

Before making the API call, the device should send an empty message to the following topic:

<clientId>/from-device/token

The access token will be received in the following message format:

{
 "metadata": {
    "timestamp": "2022-05-24T06:36:29.284356878Z"
  },
  "data": {
    "accessJwt": {
      "token": "eyJhbGciOiJSUzUxMiJ9.eyJzdWIiOiJkZXZpY2UyIiwidGVuYW50SWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJzY29wZXMiOltdLCJ0b2tlblR5cGUiOiJERVZJQ0UiLCJleHAiOjE2NTMzNzUwODksImp0aSI6IjBhYjFkZTRhLWVjOGYtNGY2OS05N2E1LTI3NzY4ZWUxZDg3MCJ9.LmlI5yO062xgeK4YFn50saLhyqI5aLjWDWfOHhp1sRt0g-0qWAmQBgGs7ptRDyJ7EciBIkzRuJ7K2hPiIuZX3lVpaX0dYnRJgOIgmmlg0MUYvHDfF7CEXg6fxh2HI-laAb6PfQ_8LhyLQ9I32O4p16LKHnXOY-A5bj5lhGPaPcI7otTmM3V5QCD_IFCFJ8FqDUS-EIM5YdTgqnzFX9rYkEsml7rGx6EIT08ulYEQ27iqs28S0sM3OWFC0sU3x0DVZZuEK0nbQWLsrh0MP5Prpnj5c6yDZZcmX5nK_g089mnpPW-t_g3dsroPJIwvRKLITjwDXL2Bt5EyPC2p5hiwtQ",
      "expiration": "2022-05-24T06:51:29.263Z"
    }
  }
}

Parameter

Description

Format

metadata.timestamp

The time that the message was created.

ISO 8601

data.accessJwt.token

The JWT token.

text

data.accessJwt.expiration

The expiration time of the token.

ISO 8601

For the intendant API calls made, the device must use this token as part of the HTTPS header authorization section:

Authorization: Bearer <token>

It is up to the device to detect if the token has expired and renew it using the method described above.
API calls that use an expired token will fail with a 403 HTTP code.
It is recommended not to save the token, but rather to ask for a new one before each batch of API calls.


Did this page help you?