Management API
Management API 是面向**机器主体（M2M）**的管理面：专用管理客户端以 client credentials 令牌完成客户端生命周期管理与用户只读查询，供接入方做开通自动化。
状态（2026-09-27）：能力处于实施收尾（M0），公开文档先行登记契约。启用方式与端点行为以对应版本发行记录为准；端到端验证完成前，本页描述的是设计契约而非已验证行为。
启用与种子
| 配置 | 默认 | 说明 |
|---|---|---|
Auth:Mgmt:Enabled | false | 总开关（部署面，启动时读取）。未启用时整组路由不存在（对外 404，不进 discovery） |
Auth:Seed:Mgmt:Enabled + Auth:Seed:Mgmt:ClientSecret | false | 播种专用管理客户端 mgmt-api（机密客户端，client credentials）与 mgmt.* scope；密钥只从私密环境变量注入 |
作用域与授权
| Scope | 允许的操作 |
|---|---|
mgmt.clients.read | 客户端列表/详情 |
mgmt.clients.write | 客户端创建/更新/删除/重置密钥 |
mgmt.users.read | 用户分页查询（零凭据字段） |
三个 scope 均绑定资源 panda-mgmt-api；端点校验 audience 与 scope 双条件——为其他资源签发的令牌即使 scope 合法也会被拒。规则：
- 只有显式持有管理 scope 权限的机密客户端能取到管理令牌；交互式应用客户端不会被授予管理 scope。
- 令牌经在线校验（token-entry validation）：吊销即时生效。
- 每笔写操作落管理审计（
mgmt.client.*动作前缀，操作者 = 调用方 clientId）。
端点
| 方法与路径 | Scope | 说明 |
|---|---|---|
GET /mgmt/v1/users | users.read | 用户分页查询（用户名/邮箱模糊搜索；响应只含 id、用户名、邮箱、昵称、状态、创建时间） |
GET /mgmt/v1/clients | clients.read | 客户端分页列表 |
GET /mgmt/v1/clients/{clientId} | clients.read | 客户端详情（不含密钥） |
POST /mgmt/v1/clients | clients.write | 创建；固定授权码 + 强制 PKCE + 刷新权限集；机密客户端密钥仅本次响应返回一次 |
PATCH /mgmt/v1/clients/{clientId} | clients.write | 更新显示名/回调/登出白名单（只覆盖显式给出的字段） |
POST /mgmt/v1/clients/{clientId}/reset-secret | clients.write | 重置密钥，明文仅返回一次 |
DELETE /mgmt/v1/clients/{clientId} | clients.write | 删除（不可逆） |
错误语义：401 invalid_token（令牌无效/已吊销）、403（缺 scope 或 audience）、429（触发速率限制，响应带 Retry-After）。
速率限制
clientId 与 IP 双维固定窗口：读 60、写 10、密钥端点（创建/重置）额外按 IP 严格限 6 每分钟（起步值，可能随部署调整）。
保留客户端
第一方与平台级客户端（me-web、admin-web、mgmt-api、fleet-api）对 Management API 只读：更新、删除与密钥重置一律被拒——这些客户端的生命周期归部署编排与种子对账管。
边界
- 用户写操作（建号、冻结、角色变更）不在 Management API 上：仍走管理后台的人工通道。
- 登录日志/审计读 scope 不在 M0 冻结面内。
- Management API 不进 discovery 元数据；路径前缀
/mgmt/v1与 OIDC 协议端点（/connect/*）显式切割。