# 鉴权与 Token

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

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

## 工作空间 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>
```

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