管理 API 鉴权与迁移

适用版本与入口

本页按 2026-10-15 核验的 new-api v1.0.0-rc.44 编写。所有管理请求使用 https://api.beeaicloud.com。文档域名用于阅读，不是 API 根地址。原生 /api/ 与 BeeBridge 的 /management-api/、/integration-api/ 是不同协议，不共享会话或错误封装。

登录会话 access_token：密码或 OAuth 登录产生的短期 Bearer 凭据，可执行本人会话及 PAT 管理。管理 PAT：长期集成使用的 nap_ 凭据，仅能访问明确授予的管理权限；不能签发或管理 PAT。模型 API Key：用于 /v1/ 等模型调用的 Key，不是管理 PAT。三者即使都使用 Authorization: Bearer ...，用途也不同。不要用客户端提交的 New-Api-User 选择或冒充账号；身份由服务端凭据确定。

登录与密码加密

先 GET /api/user/login/encryption-key。enabled=true 时，登录和密码验证都提交 password_encrypted 与 encryption_key_id，公钥标识使用响应的 kid。支持 RSA-OAEP/SHA-256 的 Base64 密文；长密码使用 v2 混合加密：RSA-OAEP 标签 password-v2 包装 32 字节 AES 密钥，AES-256-GCM 使用 12 字节 nonce、AAD password-v2:{kid}，密文尾部拼接 16 字节认证标签，格式为 v2.{wrappedKeyBase64}.{nonceBase64}.{ciphertextAndTagBase64}。enabled=false 时才发送明文 password，仍须 HTTPS。

POST /api/user/login 成功后检查 data.require_verification。如为 true，按 data.methods 用 flow_token 完成 /api/user/login/verify 或专用 Passkey 流程，再使用最终的 data.access_token。登录二次验证不等于 /api/verify 操作验证。刷新使用 POST /api/user/auth/refresh 与 new_api_refresh Cookie；退出使用 POST /api/user/auth/logout。Cookie 操作受 Origin 约束，不伪造来源绕过。

操作安全验证

先 GET /api/verify/methods?scope=access_token.generate，选择 available=true 的方法。再 POST /api/verify，提交 method、操作 scope 和该操作要求的 context。返回 data.proof_token 后，只能在同一身份/会话、同一操作上下文中，通过 X-Security-Proof 消费一次。Passkey 与 OAuth 使用专用交互流程，不能只在通用接口把 method 改成 passkey 或 oauth。

管理 PAT 与权限

使用登录会话读取 /api/user/access_tokens/catalog，按实际用途选择权限。profile:read 只够读取本人资料，不代表能管理 Key、查询全部用量或操作钱包。权限字典 /api/user/access_tokens/scopes 只提供名称，不能代替当前账号可授予权限目录。PAT 的实际权限还受账号状态、角色及实时授权约束。

失败处理与重试

同时检查 HTTP 状态与 success。错误码可能位于 code 或 data.code，HTTP 200 也可能是业务拒绝。400 SECURITY_CONTEXT_INVALID 优先核对操作上下文；401 核对凭据/会话；403 核对会话要求、scope 和账号权限；429 停止紧密重试并遵守响应退避。创建、撤销或改权请求响应丢失时，先读取状态核对，不直接重放写请求。日志只记录脱敏错误码、时间和请求 ID，禁止密码、密文、Cookie、PAT 和证明。

旧版迁移

旧 GET/POST /api/user/token 不再是新 PAT 签发入口；使用 POST /api/user/access_tokens。旧 GET /api/user/logout 改为 POST /api/user/auth/logout；旧 GET /api/verify/status 改为按目标 scope 查询 /api/verify/methods，证明从验证响应获取；旧 GET /api/oauth/state 改为 POST /api/oauth/state。已有旧 PAT 在服务器配置的过渡期限内可能仍可用，这不表示旧签发流程仍可用。退役时间从 PAT 列表的 data.legacy.retire_at 查询，不硬编码日期。公开原生注册在当前生产入口关闭，不能把上游注册路由存在当作可自行开户。

PAT →