| 4.3及以上版本 |
API keys为ThingsBoard API提供比密码认证更简单的替代方式。 与需要登录且定期过期的JWT token不同，API keys是长期有效的凭据，在配置的过期日期之前或手动吊销前一直有效。
Key features
- No login required：API keys无需交换用户名和密码即可立即使用。
- Long-lived：在您设置的过期日期前保持有效。
- Permission inheritance：key继承创建该key的用户的全部权限。
- Easy management：可随时启用、禁用或删除key。
- Simple integration：适合希望避免复杂认证代码的第三方应用。
Creating API Keys
API keys可为 您自己的账户 或 其他平台用户 创建，具体取决于您的权限。
Creating API Key for Your Account
为自己的账户创建API key：
- 点击右上角的 three-dot 菜单，选择 Account。
- 进入 Security 标签。
- 在 API keys 区域点击 Manage 按钮。
- 点击 + Generate 按钮。
- 输入API key的 description（如 Production server、Testing environment）。
- 选择有效期。
- 点击 Generate。
重要：复制并保存生成的API key，之后将不再显示。
Creating API Key for Another User
也可在用户详情页直接创建API key。 系统管理员可为可见的任意用户（tenant用户）创建API key，tenant管理员可为客户用户创建API key。 在用户详情视图中，API keys标签提供该用户的完整API key管理能力。
- 进入 Customers/Users 区域。
- 点击目标用户打开其 details。
- 进入 API keys 标签。
- 点击 + Generate 按钮。
- 输入API key的 description（如 Production server、Testing environment）。
- 选择有效期。
- 点击 Generate。
重要：复制并保存生成的API key，之后将不再显示。
注意：API key继承为其创建的用户的所有权限。
Click on the desired user to open their details.
Navigate to the API keys tab and click the + Generate button.
Using API Keys
In API requests
在 X-Authorization header中使用 ApiKey 前缀携带API key：
1
X-Authorization: ApiKey $YOUR_API_KEY_VALUE
* 将 $YOUR_API_KEY_VALUE 替换为您的API key。
示例：
1
2
3
curl -X GET --header 'Accept: application/json' \
--header 'X-Authorization: ApiKey tb_4xpayYjwrKCv5n15CvvS6IUb8vVZe55D-aoXcn_-hl9foOCxlEbtWYoy8bhhMqGt' \
'https://thingsboard.cloud/api/auth/user'
Security note：生产环境请始终使用HTTPS。在不安全的HTTP连接上执行命令会以明文传输API key，易被窃听。
In Swagger UI
使用 Swagger UI 时，可通过API key认证：
- 打开 Swagger UI。
- 点击 Authorize 按钮。
- 在 API key form (apiKey) 区域，输入带 ApiKey 前缀的 API key value：
1
ApiKey YOUR_API_KEY_VALUE
- 点击 Authorize。
注意：若同时使用JWT和API key认证，JWT 优先。
Then, click "Authorize".
Managing API keys
在API keys表格中，每个key显示以下信息：
- Created time：API key的生成时间
- Description：为key分配的自定义描述
- Status：key为激活还是已禁用
- Expiration time：key的过期日期和时间
此外，每个API key可执行以下操作：
- Enable/disable API keys — 使用每个API key旁的开关临时禁用或重新启用，而无需删除key。
- Delete API keys — 点击删除（垃圾桶）图标永久移除key。此操作不可撤销。
- Edit description — 点击 description 旁的编辑（铅笔）图标更新API key的描述。
