鉴权与限制

API Key

所有者和管理员在工作台 开发者 页面创建 Key。Key 的格式是 sr_live_ 加 32 个字符，只显示一次；我们只保存它的 SHA-256 哈希。请求时放在 Authorization 请求头里：

Authorization: Bearer sr_live_…

一个 Key 属于一个工作区，并代表整个工作区操作（所有站点，相当于负责全部站点的管理员），所以不需要传工作区 ID。请把 Key 放在服务器上，不要放进网页或 App。在工作台吊销后，Key 立即失效。

每个 Key 只拥有你勾选的权限。缺少所需权限时返回 403 forbidden，error.fields.scope 会指出缺的是哪个。

权限	允许调用
`conversations:read`	`GET /v1/conversations`、`GET /v1/conversations/{id}`
`conversations:write`	`POST …/assign`、`POST …/close`
`messages:read`	`GET /v1/conversations/{id}/messages`、`GET /v1/offline-messages`
`messages:write`	`POST /v1/conversations/{id}/messages`
`visitors:read`	`GET /v1/visitors/{id}`
`visitors:write`	`PATCH /v1/visitors/{id}`
`members:read`	`GET /v1/members`
`visitors:export`	`POST /v1/visitors/lookup`、`GET /v1/visitors/{id}/export`（见数据请求）
`visitors:delete`	`DELETE /v1/visitors/{id}`（见数据请求）
任意	`GET /v1/usage`

其他接口（站点、团队、账务、Key 管理本身）只供工作台使用，不接受 Key。

POST /v1/conversations/{id}/messages 有两种发法：

默认以“集成”身份：访客看到的是来自你的网站，客服看到的是集成。它不会把会话从待接入队列里接走，适合机器人和自动回复。只能发文字。
以客服身份：带上 "member_id": "…"，消息算作这位客服发的；和客服回复一样，会接走待接入的会话，所以 Key 还需要 conversations:write。

限制	数值	超出时
每个 Key 的请求频率	每秒 20 次	`429 rate_limited`，带 `Retry-After`
每个工作区的 API 调用量	套餐的每月额度（按 UTC 自然月，所有 Key 合计）	`402 quota_exceeded`，`fields.limit = api_calls_per_month`
有效 Key 数量	每个工作区 20 个	`402 quota_exceeded`，`fields.limit = api_keys`

GET /v1/usage 可以查看本月已用调用量和额度。被拒绝的调用不计数。不含 API 调用的套餐（免费版）不能创建 Key。