REST API

• Swagger UI
• 在哪里找到Swagger UI？
• Swagger UI中的认证
  • API key认证
  • JWT认证（已弃用）
• 附加工具

ThingsBoard提供强大的REST API，可管理所有平台实体、执行集成、实现设备自动预配置并构建自定义应用。为便于API探索与测试，ThingsBoard内置由Swagger UI驱动的交互式文档。

Swagger UI

Swagger UI是交互式工具，可用来：

• 浏览所有可用的REST API端点
• 查看请求与响应schema
• 在浏览器中直接测试API调用
• 以指定用户身份认证并执行API请求

适用于开发、调试和API探索。

在哪里找到Swagger UI？

每个ThingsBoard EU Cloud实例都有独立的Swagger UI页面。
点击下方按钮浏览ThingsBoard Cloud REST API文档：

ThingsBoard EU Cloud REST API

Swagger UI中的认证

自动认证

若已通过主ThingsBoard UI登录，Swagger UI将自动使用当前会话。

手动认证

可通过Swagger UI右上角的Authorize按钮以其他用户身份认证或授权。

步骤：

• 打开 Swagger UI
• 点击 Authorize
• 输入username与password，或在API key表单(apiKey)中粘贴API key
• 点击Authorize

注意： 同一时间只能使用一种认证方式。
若两种均已授权，JWT优先。

API key认证

API key是比JWT更简单、更适合自动化的认证方式。

• 无需登录： 不用交换密码或管理token刷新循环
• 长期有效： 可持续有效或使用您设定的过期时间
• 可撤销： 可随时禁用指定key

注意： 使用ThingsBoard UI中的API keys标签创建和管理。 详见完整文档。

使用API key

通过API key认证时，需在X-Authorization请求头中以 “ApiKey” 前缀携带：

1
X-Authorization: ApiKey $YOUR_API_KEY_VALUE

* 将$YOUR_API_KEY_VALUE替换为您的API key。

重要： API key应仅在HTTPS下使用。

示例(curl)

1
2
3
curl -X GET --header 'Accept: application/json' \
            --header 'X-Authorization: ApiKey $YOUR_API_KEY_VALUE' \
            'http://$THINGSBOARD_URL/api/auth/user'

JWT认证（已弃用）

ThingsBoard使用JWT token进行API请求认证。

登录时，用户名和密码会换取两个token：

• Access Token (JWT) - 用于API请求的短期token
• Refresh Token - Access Token过期时，可用Refresh Token获取新的Access Token而无需重新登录

默认过期时间

• Access Token 有效期为 2.5小时
• Refresh Token 有效期为 1周

如何获取JWT token？

为用户 “your_user@company.com” 与密码 “secret” 获取JWT token，执行以下命令：

1
2
3
4
curl -X POST --header 'Content-Type: application/json' \
             --header 'Accept: application/json' \
             -d '{"username":"your_user@company.com", "password":"secret"}' \
             'https://eu.thingsboard.cloud/api/auth/login'

响应：

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

认证后，在所有API请求的X-Authorization请求头中携带获取到的JWT token：

1
X-Authorization: Bearer $YOUR_JWT_TOKEN

附加工具

为便于与ThingsBoard API集成，可使用ThingsBoard官方的客户端库：

• Java REST API Client – Java客户端库，简化REST API调用
• Python REST API Client – Python客户端库，简化REST API调用

这些客户端可用于创建设备、资产、用户等实体，并管理其在ThingsBoard中的关系。