API 参考
所有端点以 /api/v3/eak/ 为前缀。两组端点，鉴权方式不同：
| 端点组 | 鉴权 |
|---|---|
| 委托与令牌（10 个） | 访问密钥签名：用工作空间 AK/SK 对请求签名，置于 Authorization 头。推荐直接用 SDK（自动签名）；HTTP 直连可复用 SDK 导出的 buildAuthorization 构造签名 |
| 工作空间与访问密钥（9 个） | 控制台登录态：面向管理台操作 |
响应统一为 JSON；错误码体系见页尾。
委托与令牌端点
GET /api/v3/eak/runtime-config
获取工作空间运行时配置（各服务的接入地址）。SDK 初始化时自动调用，一般无需手工使用。
POST /api/v3/eak/delegations
发起委托。mode 决定行为：interactive 返回授权链接（用户级授权确认），silent 直接签发（组织级授权确认，使用前必读安全考量）。
| 请求字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
agent | string | ✓ | Agent 标识 |
scopes | string[] | ✓ | 请求授权的 scope 列表 |
userId | string | silent 必填 | 被授权用户 ID（SDK 侧已改用 user: { id }，本参数为 HTTP 契约） |
mode | silent | interactive | 默认 silent | 授权模式 |
redirectUri | string | interactive 必填 | 授权完成后的回跳地址 |
state | string | interactive 必填 | 业务回跳 state |
expiresIn | number | 可选 | 令牌有效期（秒，60–86400） |
响应（silent）：{ mode: "silent", tokenType: "Bearer", delegationToken, delegateAgentToken, expiresIn, grantId, auditId }响应（interactive）：{ mode: "interactive", authorizationUrl, grantId, grantState, state, requestedScopes? }
字段名：HTTP 与 SDK 不同
HTTP 响应里委托令牌的字段名是 delegationToken（delegateAgentToken 是同值的旧别名，新代码请用前者），SDK 会把它规范为 token。silent 响应和 SDK 结果都不包含实际 scope 列表；需要确认有效性与实际范围时，调用 /delegations/introspect 并读取 active 与 scope。对照表见 SDK Reference。
interactive 响应里的 state 是服务端生成 grantState 的兼容别名，不会回显请求中的业务 state。稳定关联方式是校验 authorizationUrl 查询参数 grant_id 等于响应 grantId，并在服务端按 grantState 保存 grantId 和业务 state。用户同意后回调 redirectUri 的查询参数是 code、state（请求中的业务 state）和 grant_state（等于 grantState），不带 grantId。
POST /api/v3/eak/delegations/complete
用授权完成后的回调参数换取委托令牌（SDK：completeDelegateToken）。
| 请求字段 | 类型 | 说明 |
|---|---|---|
grantId | string | 授权记录 ID：创建响应里的 grantId，由服务端保存（回调不带） |
code | string | 回调里的一次性 code |
state | string | 回调里的 grant_state（等于创建响应的 grantState），不是业务 state |
响应：委托令牌对象，同 silent 响应形状（mode / tokenType / delegationToken / delegateAgentToken / expiresIn / grantId / auditId）。
授权确认流程端点（由 GenAuth 托管授权页调用）
以下四个端点服务于 interactive 授权确认的页面流程。使用托管授权页时无需直接调用；自建授权体验时按下表请求契约对接（响应为流程语义对象，以接口 Swagger 描述为权威）：
| 端点 | 用途 | 请求字段 |
|---|---|---|
GET /api/v3/eak/delegations/:grantId/approval-context | 解析授权登录上下文（返回授权登录入口与请求信息） | query：grant_state、redirect_uri、state? |
POST /api/v3/eak/delegations/auth/complete | 完成授权页的 OIDC 登录回调 | code、state、redirectUri |
POST /api/v3/eak/delegations/:grantId/approve | 用户批准授权，生成一次性回调 code（返回回跳地址） | userId?、userPoolId? |
POST /api/v3/eak/delegations/callback/consume | 消费一次性 code，签发委托令牌（code 一次性，重放失败） | code、state |
callback/consume 的响应为委托令牌对象（同上：delegationToken 为令牌字段名）。
POST /api/v3/eak/token-exchange
令牌兑换（RFC 8693 语义）：用委托令牌换取目标产品的访问令牌。
| 请求字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
subjectToken | string | ✓ | 委托令牌 |
resource | gumem | webagent | ✓ | 目标产品资源 |
scopes | string[] | 可选 | 本次兑换需要的产品 scope（必须是委托令牌已授 scope 的子集） |
响应：{ token, tokenType, expiresIn?, scope? }（同时提供 access_token / token_type / expires_in 蛇形别名，便于按 OAuth 惯例解析）。访问令牌的字段结构见 Token 与 Claim 参考。
POST /api/v3/eak/genauth/admin-token
换取管理面访问令牌（服务端管理操作用，如用户目录读写）。响应要点：管理面 accessToken 及其作用的用户池。
POST /api/v3/eak/delegations/introspect
在线验证委托令牌。
| 请求字段 | 类型 | 说明 |
|---|---|---|
token | string | 委托令牌 |
响应：有效时 { "active": true, ...委托令牌全部 claims }；无效、过期或格式错误时一律 { "active": false }（不泄漏失败原因）。
工作空间与访问密钥端点
工作空间（workspace）是委托体系的隔离单元：绑定用户池与产品资源，持有访问密钥。
| 端点 | 用途 |
|---|---|
GET /api/v3/eak/tenants | 列出工作空间 |
POST /api/v3/eak/tenants | 创建工作空间 |
GET /api/v3/eak/tenants/:eakTenantId | 工作空间详情 |
PATCH /api/v3/eak/tenants/:eakTenantId | 更新工作空间 |
GET /api/v3/eak/tenants/:eakTenantId/credentials | 列出访问密钥 |
POST /api/v3/eak/tenants/:eakTenantId/credentials | 创建访问密钥 |
POST /api/v3/eak/tenants/:eakTenantId/credentials/:accessKeyId/rotate | 轮换密钥 |
PATCH /api/v3/eak/tenants/:eakTenantId/credentials/:accessKeyId | 启停/更新密钥 |
DELETE /api/v3/eak/tenants/:eakTenantId/credentials/:accessKeyId | 删除密钥 |
创建工作空间（POST /tenants）请求字段：name（必填）、description?、genauthUserPoolId?、gumemProjectId?、webAgentTenantId?、delegationLoginCallbackUrl?、idempotencyKey?、status?。
创建/更新访问密钥请求字段：
| 字段 | 端点 | 说明 |
|---|---|---|
allowedScopes | 创建/更新 | 该密钥允许发起委托的 scope 白名单 |
allowedAgents | 创建/更新 | 该密钥允许委托的 Agent 白名单 |
enable | 更新 | 启用/停用密钥（停用即时生效，见吊销与应急处置） |
错误码
错误响应含 code 与 requestId。HTTP 层的 code 是 eak.* 点分码，按域分族：
| 码族 | 典型码 | 常见原因 | HTTP 状态 |
|---|---|---|---|
eak.auth.* | eak.auth.invalid_signature、eak.auth.invalid_authorization_header、eak.auth.credential_disabled | 签名错误、Authorization 头格式错、密钥已停用 | 401 |
eak.delegation.* | eak.delegation.agent_not_allowed、eak.delegation.scope_not_allowed、eak.delegation.expires_in_invalid、eak.delegation.grant_invalid_or_expired、eak.delegation.user_not_bound | Agent 或 scope 不在密钥白名单内、有效期越界、授权记录无效或过期、用户不在绑定用户池 | 400 / 403 |
eak.token_exchange.* | eak.token_exchange.upstream_failed、eak.token_exchange.invalid_upstream_response | 令牌兑换的上游调用失败 | 502 |
eak.genauth.* | eak.genauth.userpool_binding_missing、eak.genauth.no_bound_users | 工作空间未绑定用户池或池内无用户 | 400 |
SDK 提供类型化错误类
SDK 会根据 HTTP 状态和错误语义抛出 QoniAuthError、QoniPermissionDeniedError、QoniTokenExpiredError 等类型化错误；服务端返回了 eak.* 码时，error.code 仍会保留该原始码。应用优先按错误类处理通用分支，需要区分具体后端原因时再读取 error.code——字段与错误类见 SDK Reference。