Access Token

Access Token（访问令牌）用于通过 API 接口访问云平台数据。如果您需要在自己的应用程序中获取设备数据，就需要创建一个 Access Token。

什么是 Access Token

Access Token 是一串密钥字符串，相当于您账号的"通行证"。通过它，您的程序可以：

• 获取设备列表和状态
• 查询因子的实时数据和历史数据
• 向设备发送控制指令
• 管理项目和设备配置

创建 Token

1. 登录云平台，进入您的组织
2. 点击左侧菜单「Access Token」
3. 点击「创建令牌」按钮
4. 填写令牌信息：
   • 名称：便于识别的名称，如「数据大屏」「手机 App」
   • 权限：选择只读或读写权限
   • 有效期：设置令牌的过期时间
5. 点击「创建」

重要提示

创建成功后，Token 只会显示一次。请立即复制并妥善保存，关闭对话框后将无法再次查看完整 Token。

权限说明

权限	说明
只读	只能查询数据，不能修改配置或发送控制指令
读写	可以查询数据，也可以修改配置和发送控制指令

建议：

• 仅用于数据展示的场景，使用只读权限
• 需要远程控制设备时，使用读写权限
• 遵循最小权限原则，按需分配

使用 Token

在调用 API 时，需要在请求头中携带 Token：

Authorization: Bearer your-token-here

示例：获取设备列表

curl -X GET "https://dl.yengear.com/api/v2/devices/" \
  -H "Authorization: Bearer your-token-here" \
  -H "X-Organization-Slug: your-org-slug"

示例：查询因子数据

curl -X GET "https://dl.yengear.com/api/v2/factors/{factor_id}/data/" \
  -H "Authorization: Bearer your-token-here" \
  -H "X-Organization-Slug: your-org-slug"

API 文档

完整的 API 接口文档请参考 开放接口文档。

管理 Token

查看 Token 列表

在「Access Token」页面可以看到所有已创建的 Token，包括：

• 名称
• 权限类型
• 创建时间
• 过期时间
• 状态（启用/禁用）

启用/禁用 Token

点击 Token 卡片上的开关，可以临时禁用或重新启用 Token。禁用后：

• 使用该 Token 的 API 请求将被拒绝
• Token 本身不会被删除
• 随时可以重新启用

编辑 Token

点击「编辑」可以修改 Token 的名称和权限设置。

删除 Token

点击「删除」可以永久删除 Token。删除后：

• 使用该 Token 的 API 请求将被拒绝
• 无法恢复，需要重新创建

安全建议

妥善保管

• Token 等同于密码，请勿泄露给他人
• 不要将 Token 提交到代码仓库
• 不要在前端代码中硬编码 Token

定期轮换

• 建议定期更换 Token
• 如果怀疑 Token 泄露，立即禁用并创建新的

最小权限

• 只授予必要的权限
• 为不同用途创建不同的 Token
• 不再使用的 Token 及时删除

设置有效期

• 避免创建永不过期的 Token
• 根据使用场景设置合理的有效期
• 临时使用的 Token 设置较短的有效期

常见问题

Token 过期了怎么办？

Token 过期后将无法使用，需要创建新的 Token 并更新到您的应用程序中。

忘记保存 Token 怎么办？

Token 创建后只显示一次，如果忘记保存，需要删除该 Token 并重新创建。

一个组织可以创建多少个 Token？

没有数量限制，您可以根据需要创建多个 Token，建议为不同用途分别创建。

API 请求返回 401 错误？

• 检查 Token 是否正确
• 确认 Token 是否已过期或被禁用
• 检查请求头格式是否正确