鉴权与签名

控制台 API

控制台登录接口只供开发者控制台使用：

POST /api/open/console/v1/auth/login
POST /api/open/console/v1/auth/qr/generate
GET  /api/open/console/v1/auth/qr/status?qrToken=...
POST /api/open/console/v1/auth/refresh
POST /api/open/console/v1/auth/logout

控制台 Access Token 应只保存在页面内存中，刷新凭证由 HttpOnly、Secure、SameSite Cookie 保存。第三方业务服务不要复用控制台 Token。

开放 API 签名 V2

机器人和小程序等 V2 API 使用 App 凭证签名。每次请求携带：

X-Open-App-Id
X-Open-Credential-Id
X-Open-Timestamp
X-Open-Nonce
X-Open-Signature

规范请求串由八行组成，最后一行不追加换行：

UPPERCASE_HTTP_METHOD
REQUEST_PATH
CANONICAL_QUERY
APP_ID
CREDENTIAL_ID
TIMESTAMP_MILLISECONDS
NONCE
LOWERCASE_SHA256_HEX_OF_RAW_BODY

使用 App Secret 对完整规范请求串执行 HMAC-SHA256，签名输出为小写十六进制。请求体必须使用实际发送的 UTF-8 原始字节计算，不能在签名后重新格式化 JSON。

const bodyHash = sha256(rawBodyBytes).toLowerCaseHex()
const canonical = [method, path, query, appId, credentialId, timestamp, nonce, bodyHash].join('\n')
const signature = hmacSha256(appSecret, canonical).toLowerCaseHex()

服务端默认接受前后 5 分钟的时间戳，并拒绝重复 Nonce。完整规则和测试向量见后续版本的签名参考；当前可先参考后端仓库中的 signature-v2.md。

安全边界

App Secret、Webhook Secret 和刷新凭证只能在服务端保存。文档站不提供把 Secret 发送到浏览器的在线调试器；请使用本地服务端脚本测试签名。