Token 与 Claim 参考
GenAuth 的委托体系里有两种令牌，角色完全不同，字段形状也不同——集成时最常见的错误就是把它们混为一谈：
| 委托令牌（Delegate Token） | 访问令牌（兑换后） | |
|---|---|---|
| 是什么 | 授权凭据：记录"谁授权了哪个 Agent、哪些范围、多久" | 访问凭据：Agent 实际拿去调资源的令牌 |
| 面向谁 | GenAuth（用于令牌兑换与验证） | 目标资源服务 |
| 怎么来 | 授权确认完成后签发（见 快速开始） | 用委托令牌经令牌兑换（RFC 8693）换出 |
有没有 act | 没有 | 有（GenAuth 扩展结构，见下） |
两种令牌都是 JWT（RFC 7519），用标准方式验签。
表一：委托令牌完整字段
token_type 值为 eak_delegation_token 的 JWT。共 13 个顶层字段：
| 字段 | 类型 | 含义 | 契约级别 |
|---|---|---|---|
token_type | string | 恒为 eak_delegation_token | 实现细节——识别令牌种类可用，但值本身可能随版本演进，勿硬编码判等作为唯一依据 |
iss | string | 签发方 | 稳定契约 |
sub | string | 被授权用户的 ID——委托令牌的主体永远是人 | 稳定契约 |
azp | string | 发起委托的访问密钥（Access Key）ID | 稳定契约 |
agent_id | string | 被委托的 Agent 标识 | 稳定契约 |
scope | string[] | 授予的 scope 列表（格式 服务.能力:动作，如 webagent.web_search:run） | 稳定契约 |
aud | string | 恒为 genauth:token-exchange——委托令牌只被令牌兑换端点接受 | 稳定契约 |
eak_tenant_id | string | 所属工作空间 ID | 稳定契约 |
genauth_userpool_id | string | 用户所属用户池 ID | 实现细节——该字段已知存在改名演进风险，资源侧代码不得硬依赖；以本页核对版本为准 |
resource_bindings | object | 工作空间绑定的产品资源（如 { gumem: { project_id }, webagent: { tenant_id } }） | 实现细节 |
jti | string | 令牌唯一 ID | 稳定契约 |
grant_id | string | 本次授权记录 ID（贯穿授权生命周期） | 稳定契约 |
audit_id | string | 审计链 ID（见 审计与追责链） | 稳定契约 |
委托令牌没有 act
act 只出现在兑换后的访问令牌里。如果你在委托令牌里找 act，说明拿错了令牌。
表二：兑换后访问令牌的增量字段
令牌兑换（POST /api/v3/eak/token-exchange）返回的访问令牌，在目标资源的标准 claims 之外，携带以下 GenAuth 扩展字段：
| 字段 | 类型 | 含义 |
|---|---|---|
act | object | 行动者标识：{ "type": "eak_delegation", "agent_id": "...", "grant_id": "...", "access_key_id": "..." } |
exchange_id | string | 本次兑换的唯一 ID（入审计链） |
product_resource | object | 目标资源的绑定信息，形如 { "type": "gumem_project" | "webagent_tenant", "id": "..." }。是对象不是字符串——不要拿它直接和 "gumem" 判等 |
act 是 GenAuth 扩展结构，不是 RFC 8693 的标准形状
RFC 8693 定义的 act claim 是嵌套 sub 形式（"act": { "sub": "..." }）。GenAuth 的 act 是带 type 判别字段的扩展对象——资源侧解析时必须显式判断 act.type === "eak_delegation"，不要按标准嵌套形状解析。资源侧完整校验清单见 保护你的 API。
访问令牌的 sub 仍是用户——"以谁的身份"永远指向人，"由谁行动"由 act 表达。这就是委托语义在令牌里的落点。
迁移与兼容期
SDK 侧的两个已弃用形状（@eazo/anima v0.2.1 起标注 @deprecated）：
| 旧写法 | 新写法 |
|---|---|
delegateAgent({ ... }) | delegateToken({ ... }) |
顶层 userId: "usr_x" | user: { id: "usr_x" } |
双轨兼容期
服务端接口在兼容期内仍接受顶层 userId 参数。这意味着：即使你的代码已全部迁移到 user: { id }，持有你访问密钥的其他调用方仍可用旧参数发起委托。把"访问密钥的保管与轮换"当作第一道防线——威胁分析见 安全考量。
验证令牌
- 在线验证（推荐）：
POST /api/v3/eak/delegations/introspect，请求{ "token": "..." }，有效时返回{ "active": true, ...全部 claims }，无效或过期返回{ "active": false }。SDK 对应anima.genauth.introspectDelegationToken({ token })。 - 本地验签：按 JWT 标准验签后，务必校验
aud（委托令牌恒为genauth:token-exchange）与过期时间；资源侧对访问令牌还需做 scope 交集校验（见 保护你的 API）。
下一步
- 参考：API Reference
- 指南：保护你的 API：资源侧集成
- 安全：安全考量