|
1 | | - |
2 | 1 | * TOC |
3 | 2 | {:toc} |
4 | 3 |
|
5 | | -## Interactive Documentation |
| 4 | +ThingsBoard provides interactive REST API documentation via [Swagger UI](https://swagger.io/){:target="_blank"}. This tool allows you to explore available API methods, understand their parameters, and execute API requests directly from your browser. |
6 | 5 |
|
7 | | -{% if docsPrefix contains "paas/" or docsPrefix == "pe/" %} |
8 | | -ThingsBoard REST API interactive documentation is available via Swagger UI. For example, you may browse ThingsBoard Cloud API documentation using the **[Swagger UI link](https://{{hostName}}/swagger-ui.html)**. |
9 | | -{% else %} |
10 | | -ThingsBoard REST API interactive documentation is available via Swagger UI. For example, you may browse Community Edition demo server API documentation using the **[Swagger UI link](https://demo.thingsboard.io/swagger-ui.html)**. |
11 | | -{% endif %} |
| 6 | +## Where to find Swagger UI? |
12 | 7 |
|
13 | | -{% if docsPrefix contains "paas/" %} |
14 | | -{% else %} |
15 | | -Once you will install ThingsBoard server you can open an interactive documentation using the following URL: |
16 | | - |
17 | | -``` |
18 | | -http://YOUR_HOST:PORT/swagger-ui.html |
| 8 | +{% if docsPrefix == "pe/" %} |
| 9 | +Every ThingsBoard instance has its own Swagger UI page, accessible at: |
| 10 | + |
| 11 | +```text |
| 12 | +http://$THINGSBOARD_HOST:PORT/swagger-ui.html |
19 | 13 | ``` |
| 14 | +{: .copy-code} |
| 15 | + |
| 16 | +*Replace **$THINGSBOARD_HOST:PORT** with your actual ThingsBoard server address. |
20 | 17 |
|
| 18 | +For example, you may browse ThingsBoard Cloud API documentation using the [Swagger UI link](https://{{hostName}}/swagger-ui.html){:target="_blank"}. |
21 | 19 | {% endif %} |
| 20 | +{% if docsPrefix == null %} |
| 21 | +Every ThingsBoard instance has its own Swagger UI page, accessible at: |
| 22 | + |
| 23 | +```text |
| 24 | +http://$THINGSBOARD_HOST:PORT/swagger-ui.html |
| 25 | +``` |
| 26 | +{: .copy-code} |
22 | 27 |
|
23 | | -Documentation page will automatically use your credentials, if you have previously authorized on the main login page. |
24 | | -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: |
| 28 | +*Replace **$THINGSBOARD_HOST:PORT** with your actual ThingsBoard server address. |
25 | 29 |
|
26 | | -{% include images-gallery.html imageCollection="swagger-ui" %} |
| 30 | +For example, you may browse Community Edition demo server API documentation using the [Swagger UI link](https://demo.thingsboard.io/swagger-ui.html){:target="_blank"}. |
| 31 | +{% endif %} |
| 32 | +{% if docsPrefix == "paas/" %} |
| 33 | +Every [ThingsBoard Cloud](https://thingsboard.cloud/){:target="_blank"} instance has its own Swagger UI page. |
| 34 | +Browse ThingsBoard Cloud REST API documentation by clicking the button below: |
27 | 35 |
|
28 | | -{% if docsPrefix == "pe/" or docsPrefix contains "paas/" %} |
| 36 | +<br> |
| 37 | +<p><a href="https://thingsboard.cloud/swagger-ui.html" target="_blank" class="n-button add-device">ThingsBoard Cloud REST API documentation</a></p> |
| 38 | +{% endif %} |
| 39 | +{% if docsPrefix == "paas/eu/" %} |
| 40 | +Every [ThingsBoard EU Cloud](https://eu.thingsboard.cloud/){:target="_blank"} instance has its own Swagger UI page. |
| 41 | +Browse ThingsBoard EU Cloud REST API documentation by clicking the button below: |
29 | 42 |
|
30 | | -The easiest way to get your account is to use [ThingsBoard Cloud](https://{{hostName}}/signup) server. |
| 43 | +<br> |
| 44 | +<p><a href="https://eu.thingsboard.cloud/swagger-ui.html" target="_blank" class="n-button add-device">ThingsBoard EU Cloud REST API documentation</a></p> |
| 45 | +{% endif %} |
31 | 46 |
|
32 | | -{% else %} |
| 47 | +## How to authenticate in Swagger UI? |
| 48 | + |
| 49 | +- If you are already logged in via the main ThingsBoard login page, Swagger UI will automatically use your credentials. |
| 50 | +- You can manually authenticate or authorize as a different user using the "**Authorize**" button in the top-right corner of the Swagger page. Enter the username and password. Then, click "Authorize". |
33 | 51 |
|
34 | | -See **[live-demo](/docs/{{docsPrefix}}user-guide/live-demo/)** page for more details how to get your account. |
| 52 | +{% include images-gallery.html imageCollection="swagger-ui" %} |
35 | 53 |
|
| 54 | +{% if docsPrefix == "pe/" or docsPrefix contains "paas/" or (docsPrefix == "paas/eu/") %} |
| 55 | +The easiest way to get your account is to use [ThingsBoard Cloud](https://{{hostName}}/signup){:target="_blank"} server. |
| 56 | +{% else %} |
| 57 | +See [Live Demo ThingsBoard](/docs/{{docsPrefix}}user-guide/live-demo/){:target="_blank"} page for more details how to get your account. |
36 | 58 | {% endif %} |
37 | 59 |
|
38 | | -## JWT Tokens |
| 60 | +## How API authentication works? |
39 | 61 |
|
40 | | -ThingsBoard uses [JWT](https://jwt.io/) tokens for representing claims securely between the API client (browser, scripts, etc) and the platform. |
41 | | -When you login to the platform, your username and password is exchanged to the pair of tokens. |
| 62 | +ThingsBoard uses [JWT](https://jwt.io/){:target="_blank"} tokens for representing claims securely between the API client (browser, scripts, etc) and the platform. |
| 63 | +When you login to the platform, your username and password is exchanged to the pair of tokens. |
42 | 64 |
|
| 65 | +- **Access Token (JWT)** – short-lived token, used for executing API calls. |
| 66 | +- **Refresh Token** – used to obtain a new access token when the current one expires. |
43 | 67 |
|
44 | | -{% if docsPrefix contains "paas/" %} |
45 | | -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. |
46 | | -Default expiration time values are 2.5 hours and 1 week respectively. |
| 68 | +{% if docsPrefix == "pe/" or docsPrefix == null %} |
| 69 | +The expiration time of main and refresh tokens is [configurable](/docs/user-guide/install/{{docsPrefix}}config/){:target="_blank"} in system settings via **JWT_TOKEN_EXPIRATION_TIME** and **JWT_REFRESH_TOKEN_EXPIRATION_TIME** parameters. |
| 70 | +{% endif %} |
47 | 71 |
|
48 | | -See sample command below to get the token for user "[email protected]" and password "secret": |
| 72 | +Default token expiration: |
49 | 73 |
|
50 | | -{% else %} |
51 | | -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. |
52 | | -The expiration time of main and refresh tokens is [configurable](/docs/user-guide/install/{{docsPrefix}}config/) in system settings |
53 | | -via JWT_TOKEN_EXPIRATION_TIME and JWT_REFRESH_TOKEN_EXPIRATION_TIME parameters. Default expiration time values are 2.5 hours and 1 week respectively. |
| 74 | +- **Access Token** is valid for **2.5 hours**. |
| 75 | +- **Refresh Token** is valid for **1 week**. |
54 | 76 |
|
55 | | -See sample command below to get the token for user "[email protected]", password "tenant" and server "THINGSBOARD_URL": |
| 77 | +## How to obtain a JWT token? |
56 | 78 |
|
| 79 | +{% if docsPrefix == null or docsPrefix == "pe/" %} |
| 80 | +To obtain a JWT token for the user " [email protected]" with password "tenant" on "$THINGSBOARD_URL" (actual ThingsBoard server address), execute the following command: |
| 81 | + |
| 82 | +```text |
| 83 | +curl -X POST --header 'Content-Type: application/json' \ |
| 84 | + --header 'Accept: application/json' \ |
| 85 | + -d '{"username":"[email protected]", "password":"tenant"}' \ |
| 86 | + 'http://$THINGSBOARD_URL/api/auth/login' |
| 87 | +``` |
| 88 | +{: .copy-code} |
| 89 | +{% endif %} |
| 90 | +{% if docsPrefix == "paas/" %} |
| 91 | +To obtain a JWT token for the user " [email protected]" with password "secret", execute the following command: |
| 92 | + |
| 93 | +```text |
| 94 | +curl -X POST --header 'Content-Type: application/json' \ |
| 95 | + --header 'Accept: application/json' \ |
| 96 | + -d '{"username":"[email protected]", "password":"secret"}' \ |
| 97 | + 'https://thingsboard.cloud/api/auth/login' |
| 98 | +``` |
| 99 | +{: .copy-code} |
| 100 | +{% endif %} |
| 101 | +{% if docsPrefix == "paas/eu/" %} |
| 102 | +To obtain a JWT token for the user " [email protected]" with password "secret", execute the following command: |
| 103 | + |
| 104 | +```text |
| 105 | +curl -X POST --header 'Content-Type: application/json' \ |
| 106 | + --header 'Accept: application/json' \ |
| 107 | + -d '{"username":"[email protected]", "password":"secret"}' \ |
| 108 | + 'https://eu.thingsboard.cloud/api/auth/login' |
| 109 | +``` |
| 110 | +{: .copy-code} |
57 | 111 | {% endif %} |
58 | 112 |
|
59 | | -{% capture tabspec %}token |
60 | | -A,get-token.sh,shell,resources/get-token.sh,/docs/reference/resources/get-token.sh |
61 | | -B,response.json,json,resources/get-token-response.json,/docs/reference/resources/get-token-response.json{% endcapture %} |
62 | | -{% include tabs.html %} |
| 113 | +Response: |
63 | 114 |
|
64 | | -- Now, you should set 'X-Authorization' header to "Bearer $YOUR_JWT_TOKEN". **Make sure** you use main JWT token and not the refresh token. |
| 115 | +```json |
| 116 | +{"token":"$YOUR_JWT_TOKEN", "refreshToken":"$YOUR_JWT_REFRESH_TOKEN"} |
| 117 | +``` |
| 118 | +{: .copy-code} |
| 119 | + |
| 120 | +Once authenticated, use the obtained JWT token in the X-Authorization header for all API requests: |
| 121 | + |
| 122 | +```text |
| 123 | +X-Authorization: Bearer $YOUR_JWT_TOKEN |
| 124 | +``` |
| 125 | +{: .copy-code} |
65 | 126 |
|
66 | | -## Java REST API Client |
| 127 | +## Additional tools |
67 | 128 |
|
68 | | -ThingsBoard team provides client library written in Java to simplify consumption of the REST API. |
69 | | -Please see Java REST API Client [documentation page](/docs/{{docsPrefix}}reference/rest-client/) for more details. |
| 129 | +For easier integration with the ThingsBoard API, you can use ThingsBoard team client libraries: |
70 | 130 |
|
71 | | -## Python REST API Client |
| 131 | +- [Java REST API Client](/docs/{{docsPrefix}}reference/rest-client/){:target="_blank"} – client library written in Java to simplify consumption of the REST API. |
| 132 | +- [Python REST API Client](/docs/{{docsPrefix}}reference/python-rest-client/){:target="_blank"} – client library written in Python to simplify the consumption of the REST API. |
72 | 133 |
|
73 | | -ThingsBoard team provides client library written in Python to simplify consumption of the REST API. |
74 | | -Please see Python REST API Client [documentation page](/docs/{{docsPrefix}}reference/python-rest-client/) for more details. |
| 134 | +These clients allow you to create devices, assets, users, and other entities, as well as manage their relationships within ThingsBoard. |
0 commit comments