服务端集成

业务服务端负责保护应用密钥、执行业务权限校验，并为设备申请短效入房凭证。设备端不应直接调用 Token 服务，也不应持有应用密钥；设备端只接收业务服务端下发的 peer_id 和 token。

接口鉴权

服务端 API 签名与探鸽云端 OpenAPI 服务端签名一致，详见 服务端API接口签名算法Demo。

申请入房凭证

向 Token 服务请求 peer_id 和 token：

POST https://api-tirtc.tange365.com/v1/token/room
Content-Type: application/json
Authorization: TGV1-HMAC-SHA256 ...
X-Tg-App-Id: {AppId}

请求 Body：

{
  "room_id": "order-20260611-001",
  "device_id": "device-001"
}

响应示例：

{
  "peer_id": "room_peer_order_20260611_001_device_001",
  "token": "v1.{claimB64}.{sig}"
}

peer_id 是下发给设备端的连接目标标识，设备端应把它原样传给 TiRTC TiRtcWhipConnect 接口，不要解析、拼接或改写。

推荐服务端流程

1. 校验登录用户、设备和业务房间之间的权限关系。
2. 使用服务端密钥调用 Token 服务。
3. 确认响应成功后，仅把 peer_id 和 token 下发给设备。
4. 不在日志中打印完整 token，只记录 room_id、device_id、请求时间和错误码。
5. 凭证过期或建连失败时，重新申请新凭证，不复用旧 token。

字段约束

字段	说明
room_id	业务侧逻辑房间 ID，用于标识设备要加入的同一个房间。建议使用稳定、可追踪且不包含敏感信息的业务 ID。
device_id	设备唯一标识，需与业务权限校验结果一致。
peer_id	设备端连接目标标识，由 Token 服务返回，业务服务端只负责安全下发。
token	短效连接凭证，只能和本次返回的 peer_id 配套使用。

常见错误

HTTP 状态码	说明
400	请求参数错误，例如 room_id 或 device_id 为空。
401	App 鉴权失败，检查 X-Tg-App-Id、TGV1 签名时间、签名 Header 和 Body SHA-256。
403	当前应用或设备没有入房权限。