# 登录、账号、安全与授权接口
这一层负责“谁在调用、能做什么、授权额度是多少”。登录接口服务于交互式用户；长期系统集成应使用独立 API Token，并只授予必要权限。
本页覆盖 **35** 个接口。每一行都回答五件事：接口地址、它做什么、何时调用、如何确认完成、谁可以调用。参数字段的精确定义以同版本 OpenAPI 为准。
> “业务接口”可以由 WebUI 或第三方系统按权限调用；“管理员接口”需要后台管理员；“内部接口/内部回调”只允许产品组件之间使用。
## API Token
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
| `GET /api/v2/security/api-tokens` | 查询 API Token 摘要和是否支持再次显示。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口
`security.tokens.view` | 无业务参数 |
| `POST /api/v2/security/api-tokens` | 创建受限 API Token。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.tokens.manage` | CreateApiTokenRequest |
| `DELETE /api/v2/security/api-tokens/{tokenId}` | 立即吊销 API Token。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.tokens.manage` | tokenId（必填） |
| `PUT /api/v2/security/api-tokens/{tokenId}` | 修改现有 API Token 的名称、权限、IP 白名单和有效期。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.tokens.manage` | tokenId（必填）、UpdateApiTokenRequest |
| `POST /api/v2/security/api-tokens/{tokenId}/reveal` | 显示完整 API Token。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.tokens.manage` | tokenId（必填） |
| `POST /api/v2/security/api-tokens/{tokenId}/rotate` | 轮换 API Token。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.tokens.manage` | tokenId（必填） |
## 安全审计
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
| `GET /api/v2/security/audit` | 分页查询安全审计。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口
`security.audit.view` | page、pageSize、eventType、outcome、before |
## 日志与安全
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
| `GET /api/v2/security/permissions` | 查询全部可用于组合角色的权限点。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口
`authenticated` | 无业务参数 |
| `DELETE /api/v2/security/rtsp-auth` | 删除 RTSP 鉴权凭据。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.rtsp.manage` | mediaServerId、username |
| `GET /api/v2/security/rtsp-auth` | 查询 RTSP 鉴权凭据。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口
`security.rtsp.view` | mediaServerId、username |
| `POST /api/v2/security/rtsp-auth` | 创建或更新 RTSP 鉴权凭据。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.rtsp.manage` | SaveRtspAuthCredentialRequest |
| `POST /api/v2/security/rtsp-auth/test` | 验证指定 RTSP 账号能否构造 Digest 响应。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.rtsp.manage` | TestRtspAuthCredentialRequest |
## 角色与权限
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
| `GET /api/v2/security/roles` | 查询内置和自定义角色及权限点。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口
`security.roles.view` | 无业务参数 |
| `POST /api/v2/security/roles` | 使用权限点创建自定义角色。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.roles.manage` | SaveRoleRequest |
| `DELETE /api/v2/security/roles/{roleId}` | 删除尚未绑定用户的自定义角色。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.roles.manage` | roleId（必填） |
| `PUT /api/v2/security/roles/{roleId}` | 修改自定义角色并立即使相关用户旧会话失效。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.roles.manage` | roleId（必填）、SaveRoleRequest |
## 用户
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
| `GET /api/v2/security/users` | 查询管理台用户及角色绑定。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 管理员接口
`security.users.view` | 无业务参数 |
| `POST /api/v2/security/users` | POST /api/v2/security/users。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.users.manage` | CreateUserRequest |
| `DELETE /api/v2/security/users/{userId}` | 软删除用户、撤销会话及其 API Token。 | 用户明确确认删除或清理后调用；调用前应先展示影响范围。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.users.manage` | userId（必填） |
| `PUT /api/v2/security/users/{userId}` | 修改用户状态及角色绑定，并立即撤销旧会话。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.users.manage` | userId（必填）、UpdateUserRequest |
| `POST /api/v2/security/users/{userId}/password` | 管理员重置用户密码并撤销全部会话。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.users.manage` | userId（必填）、ChangePasswordRequest |
| `POST /api/v2/security/users/{userId}/sessions/revoke` | 撤销指定用户的全部登录会话。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 管理员接口
`security.users.manage` | userId（必填） |
## 登录与会话
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
| `POST /api/v2/auth/bootstrap` | 从服务器本机初始化首个超级管理员。 | 只在平台首次初始化、还没有管理员账号时使用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 仅首次初始化
`专用流程` | BootstrapAdminRequest |
| `GET /api/v2/auth/bootstrap-status` | 查询是否需要首次初始化管理员。 | 只在平台首次初始化、还没有管理员账号时使用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 公开入口
`专用流程` | 无业务参数 |
| `GET /api/v2/auth/captcha/{id}` | 查看一次性图形验证码图片。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 公开入口
`专用流程` | id（必填） |
| `POST /api/v2/auth/captcha/{id}/refresh` | 作废当前验证码并签发新的随机挑战。 | 用户登录、续签或退出交互式会话时使用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 公开入口
`专用流程` | id（必填） |
| `POST /api/v2/auth/change-password` | 当前用户修改自己的密码并撤销全部会话。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口
`authenticated` | ChangePasswordRequest |
| `POST /api/v2/auth/login` | 用户名密码登录。 | 用户登录、续签或退出交互式会话时使用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 公开入口
`专用流程` | LoginRequest |
| `POST /api/v2/auth/logout` | 退出当前会话并立即撤销服务端会话。 | 用户登录、续签或退出交互式会话时使用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口
`authenticated` | 无业务参数 |
| `GET /api/v2/auth/me` | 查看当前登录用户、角色和权限点。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口
`authenticated` | 无业务参数 |
| `POST /api/v2/auth/refresh` | 旋转 Refresh Token 并签发新的短时访问令牌。 | 用户登录、续签或退出交互式会话时使用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 公开入口
`专用流程` | 无业务参数 |
## 产品授权
| 接口 | 讲人话 | 什么时候用 | 调完看什么 | 身份 / 权限 | 主要输入 |
|---|---|---|---|---|---|
| `GET /api/v2/licensing/export/{licenseId}` | GET /api/v2/licensing/export/{licenseId}。 | 页面加载、刷新状态或按条件检索数据时调用。 | 检查 Content-Type、文件长度或 Range 响应，不要按普通 JSON 解析。 | 业务接口
`authenticated` | licenseId（必填） |
| `POST /api/v2/licensing/import` | POST /api/v2/licensing/import。 | 用户提交业务动作或配置变更时调用。 | 重新读取目标资源，确认保存值和运行状态都已更新。 | 业务接口
`system.config.manage` | AkLicenseImportRequest |
| `GET /api/v2/licensing/request` | GET /api/v2/licensing/request。 | 页面加载、刷新状态或按条件检索数据时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口
`authenticated` | 无业务参数 |
| `GET /api/v2/licensing/status` | GET /api/v2/licensing/status。 | 做页面概览、运行监控或排障时调用。 | 以返回数据、分页总数和目标资源的当前状态为准。 | 业务接口
`authenticated` | 无业务参数 |
## 接口字段与示例
本页故意先讲清业务用途，不把几百个字段塞进说明文字。真正编码时，请使用与部署版本一起提供的 OpenAPI 和 Postman 资产查看请求体、响应体、枚举、文件类型与示例；不要拿网站最新契约调用旧版本服务。