REST API

• Interactive Documentation
• JWT Tokens
• Java REST API Client
• Python REST API Client

Interactive Documentation

ThingsBoard REST API interactive documentation is available via Swagger UI. For example, you may browse ThingsBoard Cloud API documentation using the Swagger UI link.

Once you will install ThingsBoard server you can open an interactive documentation using the following URL:

1
http://YOUR_HOST:PORT/swagger-ui.html

Documentation page will automatically use your credentials, if you have previously authorized on the main login page. You may use “Authorize” button in the top right corner of the documentation page to manually authorize. You may also use this button to authorize as a different user. See below:

The easiest way to get your account is to use ThingsBoard Cloud server.

JWT Tokens

ThingsBoard uses JWT tokens for representing claims securely between the API client (browser, scripts, etc) and the platform. When you login to the platform, your username and password is exchanged to the pair of tokens.

The main token is short-lived token you should use to perform the API calls. The refresh token is used to get new main token once it is expired. The expiration time of main and refresh tokens is configurable in system settings via JWT_TOKEN_EXPIRATION_TIME and JWT_REFRESH_TOKEN_EXPIRATION_TIME parameters. Default expiration time values are 2.5 hours and 1 week respectively.

See sample command below to get the token for user “tenant@thingsboard.org”, password “tenant” and server “THINGSBOARD_URL”:

1
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' -d '{"username":"tenant@thingsboard.org", "password":"tenant"}' 'http://THINGSBOARD_URL/api/auth/login'

1
{"token":"$YOUR_JWT_TOKEN", "refreshToken":"$YOUR_JWT_REFRESH_TOKEN"}

• Now, you should set ‘X-Authorization’ header to “Bearer $YOUR_JWT_TOKEN”. Make sure you use main JWT token and not the refresh token.

Java REST API Client

ThingsBoard team provides client library written in Java to simplify consumption of the REST API. Please see Java REST API Client documentation page for more details.

Python REST API Client

ThingsBoard team provides client library written in Python to simplify consumption of the REST API. Please see Python REST API Client documentation page for more details.