API 认证、权限与错误处理

生产 API 基础地址通常为 https://<host>/api/v2。默认使用 UTF-8 JSON；文件、验证码、SDP 和 WebSocket 例外。

flowchart LR
    A[请求携带 API Token] --> B[验证身份]
    B --> C[检查具体权限]
    C --> D[执行业务并返回 TraceId]
    D --> E[按状态码和错误码处理]

服务端集成认证

管理员通过交互式会话创建 API Token。为每个系统单独创建，不共享：

Authorization: Bearer ak_pat_<TOKEN>
Accept: application/json

创建时设置用途名称、最小权限、过期时间和可选 IP CIDR。完整 Token 不得进入浏览器 bundle、URL、Git、截图、工单或普通日志。

常见最小权限：

• 只播放：channels.view、streams.view、streams.play
• 查录像：增加 recordings.view、recordings.play
• 下载录像：再增加 recordings.download
• 控制设备：devices.view、devices.control
• 对讲：增加 devices.talk
• 监控采集：dashboard.view、nodes.view、system.view

普通 Token 不应拥有用户、角色、Token 管理或整体生命周期权限。

管理员可在 用户权限 → API Token 展开某个 Token，查看实际权限码、IP 白名单和有效期，并直接修改。修改不会改变 Token 字符串，但新权限、IP 和有效期立即用于后续 API、播放新连接和租约续期；收回播放权限后，旧租约不能再续租或重连。

浏览器会话

WebUI 使用 ak_access、ak_refresh、ak_csrf Cookie。非 GET/HEAD/OPTIONS 写请求还需将 CSRF Cookie 值放进 X-AK-CSRF。Refresh Token 会旋转，旧值重放被拒绝。

第三方后端不要模拟这套登录流程。第三方浏览器应用也不应把长期 Token 放在 localStorage；推荐调用自己的同源后端，由后端按用户身份代理最小操作。

HTTP 状态

安全错误通常包含 code、message 和 traceId，例如 authentication_required、permission_denied、csrf_invalid。部分业务错误可能使用 ProblemDetails 或其他结构，客户端必须保留 Content-Type 与原始响应，不能假定所有非 2xx 相同。

重试规则

• GET 的网络错误可按 1、2、5、10 秒退避。
• POST、PUT、DELETE 默认不自动重放。
• 收到 202 后查询命令，不重新创建。
• 409 先查询当前资源或活动会话。
• 客户端超时不代表服务端没有执行。

Swagger 与接口目录

Release 与 Debug 都可以携带 Swagger/Knife4j，但页面、资源和 OpenAPI JSON 需要已登录 WebUI 的交互式后台会话；普通 API Token 不能枚举接口目录。无人值守集成应使用随版本交付的 OpenAPI 文件。

轮换 Token

先创建并部署新 Token，观察新凭据已承载流量，再吊销旧 Token。吊销后验证旧值立即失败，审计中能看到创建、使用摘要与吊销行为。