# API 认证、权限与错误处理

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

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

## 服务端集成认证

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

```http
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 状态

| 状态 | 调用方行为 |
|---:|---|
| 200/201 | 解析资源，同时检查业务状态 |
| 202 | 保存 commandId/sessionId，等待终态 |
| 204 | 成功且无响应体 |
| 400 | 修正参数或状态，不盲目重试 |
| 401 | 更新、轮换或检查 Token |
| 403 | 缺权限、CSRF 或交互式限制，不自动扩大权限 |
| 404 | 核对版本、资源 ID 和入口是否对当前模式开放 |
| 409 | 查询现有资源/命令，再决定补偿 |
| 413 | 调整请求体、文件或代理限制 |
| 429 | 按 `Retry-After` 和退避处理 |
| 500/502/503 | 保存 TraceId，检查依赖后谨慎重试 |

安全错误通常包含 `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。吊销后验证旧值立即失败，审计中能看到创建、使用摘要与吊销行为。