跳转到内容

鉴权

在 HTTP 请求头中发送完整的不透明 token:

Authorization: Bearer <api-key>

Organization API Key 代表一个组织,不带 acting User。User API Key 代表一个组织内的 End User。Console 登录及组织成员关系使用独立管理凭据。

接口组 凭据
/api/v1/org 及 End User、Key 创建 Organization API Key
/api/v1/org/users/{userId} 下的 目录发现、Session、Turn、Client Tool、File、Scheduler 和 Realtime Organization API Key
/api/v1/user 下的模板摘要和 Agent 关联 User API Key
User 前缀的生命周期;Turn、交互、普通文件上传、Scheduler 和 Realtime Connection User API Key
/api/v1/connectors/ws Organization API Key 和显式 X-Ti-Connector-Id
/api/v1/connectors/jwks 公开验证公钥,无需凭据
/api/v1/drive-downloads/{ticket}, /api/v1/drive-uploads/{ticket} 仅短期票据

每条接口的凭据要求见生成的 API 参考。Organization Key 只能调用明确允许的组织接口,不能冒充用户。Key 没有可编辑的逐 Key 权限列表。

Organization Key 保存在应用后端。设置 BASE_URL 和 ORGANIZATION_API_KEY,创建 End User,再将返回的 user.userId 保存为 USER_ID 用于显式所有者流程;仅在集成仍使用保留的 User-Key 接口时签发 User Key:

终端窗口
curl --fail-with-body "$BASE_URL/api/v1/org/users" \
-H "Authorization: Bearer $ORGANIZATION_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"displayName":"Application user","externalId":"app-user-001"}'
curl --fail-with-body "$BASE_URL/api/v1/org/users/$USER_ID/api-keys" \
-H "Authorization: Bearer $ORGANIZATION_API_KEY" \
-H 'Content-Type: application/json' \
--data '{"name":"Application key"}'

保存应用身份与 user.userId 的映射。externalId 在组织内唯一,带它的创建请求可以安全重试:首次请求返回 201 和新用户;值完全相同的重复请求返回 200 和未作修改的已有用户,已停用的用户也照原样返回。与已有值不同、但在忽略大小写和重音的比较下相等的值(例如 Ab3X 与 aB3x)返回 409 resource_conflict。用户创建结果不明时,重新发送同一请求即可得到 userId。不带 externalId 时,每次请求都会创建新用户。

Key 创建响应在 apiKey 中返回元数据,在 token 中交付 secret。将 token 安全保存为 USER_API_KEY。只有创建和轮换响应交付 secret,列表无法找回。签发结果不明时先核对元数据;丢失 secret 后需要明确轮换。

用 GET /api/v1/org/users/{userId}/api-keys 查看 Key,用 POST /api/v1/org/user-api-keys/{id}/rotate 或 /revoke 轮换或吊销。后续私有执行使用有效 User Key。

创建 End User 不会建立 Platform Account、Membership、Agent 或管理权限。Token、上传链接和下载链接都是凭据,应保存在共享日志、URL 和代码仓库之外。

Organization Key 可以直接管理生命周期、文本与音频 Turn、Client Tool、File/Drive、Scheduler 和 Realtime,无需 User Key。所选 User 始终是资源所有者,隐藏 Test 身份和管理身份不能作为普通目标。禁用的普通用户保留受支持的已有数据读取、设置和清理能力;创建 Session 和调用模型生成标题仍要求用户启用。Organization 列表还接受 status=deleted,用于读取已删除 Scheduler 的历史。

Scheduler 绑定创建它的确切 Organization Key,包括从 Turn 工具调用创建的计划。轮换或撤销该凭据会阻止后续触发,保留已接受的 Turn 和历史。后端可以使用新的有效 Key、当前 If-Match 和 enabled: true,自动调用 PATCH /api/v1/org/users/{userId}/schedulers/{schedulerId} 恢复;一次性计划过期后还需提供未来时间。重放旧创建回执不会重新授权后续执行。

旧凭据失效会结束它打开的 Realtime Connection,使未使用的 connect token 失效。用有效 Key 恢复已接受 Turn 的结果,再在同一 Session 上打开新连接。已接受的常驻 Turn 会保留,但不再启动后续轮次。Organization 签发的文件票据在凭据失效后拒绝新的兑换请求;已获准的传输可在原有限制内完成。保留的 User-Key 票据有效期不变。