🤖 给 AI 的参考

这是 Hearo（听见）的《鉴权与 Token》文档，可作为开发参考。文档链接：https://hearo.apps.aisp24.com/docs/auth.md

鉴权与 Token

两层凭据：工作空间 API Key（服务端）+ 客户端 Token / 设备接入密码（终端）。完整接入流程见「客户端与接入模型」

Hearo 的接入鉴权是两层：工作空间 API Key 给你的服务端用（管理客户端、签发 Token、调度智能体）；客户端凭据给终端用（连接 MQTT、WSS 或 WebRTC（实验）），有两种形态：客户端 Token（JWT，通用）和设备接入密码（短密码，MQTT 设备专用）。终端只持有客户端凭据，永不接触 API Key。端到端流程、管理 API、各传输怎么带凭据，集中在客户端与接入模型，本页讲凭据本身。

工作空间 API Key（服务端）

在控制台 API Key 页创建（需要工作空间管理员角色），形如 hk_xxx（只显示一次，平台只存哈希）。用 Authorization: Bearer hk_xxx 调用 /api/v1/* 管理接口：创建客户端、签发客户端 Token、切换房间、调度智能体、查用量。当作机密保存在你的后端，绝不下发到终端。可创建多把、可吊销。

ℹ️ 工作空间 = 唯一的组织边界：API Key 是工作空间级的——它管理整个工作空间下的客户端与房间。一个用户可创建/加入多个工作空间，工作空间之间完全独立（房间、设备各自隔离，同名互不影响）。

客户端 Token（终端，通用）

由你的后端用 API Key 现签发（POST /api/v1/clients/{id}/token），或在控制台 → 设备页对某台设备点「生成 Token」。它是标准 HS256 JWT，只证明身份（sub=clientId），不含房间——进哪个房间由 client→room 映射决定。签名用工作空间的隐藏签名密钥（自动生成、永不展示、支持轮换），可签长期或有效期 Token。

声明	类型	说明
iss	string	workspaceId（所属工作空间，验签按它找密钥）
sub	string	clientId（客户端身份）
aud	string	`hearo-client`（固定）
exp	number	过期时间（可选）；省略 = 长期 Token（适合写死固件）
jti	string	Token 唯一 ID（用于单个吊销）

设备接入密码（终端，MQTT 专用）

hkd_ 开头的短随机密码（约 28 字符），在控制台 → 设备页为某台设备生成；可反复查看（加密存储）、可一键重置（旧密码立即失效）。MQTT CONNECT 时直接作 password 使用，效果等同该设备的客户端 Token。适合密码字段有长度限制、或不便烧录长 JWT 的固件。

连接时怎么带

text

MQTT:      124.174.6.145:2883   password = <客户端 Token> 或 <设备接入密码>（username 规则见各协议页）
WebSocket: wss://hearo-gw.apps.aisp24.com/v1/connect?token=<客户端 Token>
WebRTC（实验）: POST https://hearo-gw.apps.aisp24.com/v1/webrtc/offer
                Authorization: Bearer <客户端 Token>

签发与连接示例见客户端与接入模型。WSS 与 WebRTC（实验）务必走 TLS（wss/https）；WebRTC（实验）拒绝 query token，只接受一个 Authorization: Bearer 请求头。MQTT broker 默认明文 TCP，生产建议部署侧加 TLS 终结，或优先用可随时重置的设备接入密码。