AgentOS 开发文档

简体中文

English

简体中文

English

主题

AuthKit ​

AuthKit 是 AgentOS 为第三方应用提供的 OAuth 风格授权服务。
它让第三方 App 能够安全获得 AgentOS 用户身份信息，而无需直接处理底层账号系统。

它解决什么问题 ​

AuthKit 帮你处理：

  • 第三方 App 向 AgentOS 用户发起授权请求
  • 用户在 AgentOS 桌面端确认授权
  • 授权码交换为 access token
  • 通过 access token 获取用户信息（userId、name、avatarUrl）
  • 授权的吊销与生命周期管理

最适合什么场景 ​

  • 你的 App 需要识别当前 AgentOS 用户的身份
  • 你需要在多设备间关联同一个用户
  • 你需要在 DiscoveryKit 或 TransferKit 中标识"谁发的文件"
  • 你需要基于用户维度做数据隔离

授权流程 ​

AuthKit 采用类似 OAuth 授权码模式：

  1. App 调用 POST /authkit/authorize，携带 AppKit 颁发的 bearer token
  2. 如果该 App 之前已被授权过，直接返回 authCode（status=granted）
  3. 如果是首次授权，返回 requestId（status=pending），等待用户确认
  4. App 轮询 GET /authkit/authorize/<requestId>/status 直到状态变为 granted
  5. 获得 authCode 后，调用 POST /authkit/token 换取 accessToken
  6. 使用 accessToken 调用 GET /authkit/userinfo 获取用户信息

核心能力 ​

发起授权 ​

常见入口：

  • SDK（TypeScript）：sdk.authkit.authorize(bearerToken, { scopes: ['profile'], appName: 'MyApp' })
  • SDK（Python）：await sdk.authkit.authorize(bearer_token, {"scopes": ["profile"], "appName": "MyApp"})
  • HTTP：POST /authkit/authorize

轮询授权状态 ​

  • SDK：sdk.authkit.getStatus(bearerToken, requestId)
  • HTTP：GET /authkit/authorize/<requestId>/status

返回的 status 包括：pending、granted、denied、timeout

换取 Token ​

  • SDK：sdk.authkit.exchangeToken(bearerToken, { authCode })
  • HTTP：POST /authkit/token

成功后返回：

  • accessToken：后续用于获取用户信息
  • userInfo：包含 name 和 avatarUrl
  • userId：用户与该 App 的唯一标识（基于登录 ID 和 bundleId 的哈希）

获取用户信息 ​

  • SDK：sdk.authkit.getUserInfo(accessToken)
  • HTTP：GET /authkit/userinfo（以 accessToken 作为 Bearer token）

吊销授权 ​

  • SDK：sdk.authkit.revoke(bearerToken)
  • HTTP：POST /authkit/revoke

与 AgentOS 登录状态的关系 ​

AuthKit 的 access token 有效性跟随 AgentOS 登录状态：

  • 用户登出 → 所有已授权 App 的 token 失效，App 收到 logout 事件
  • 切换账号 → 所有 grants 和 token 被清除，App 收到 account_switch 事件
  • 同账号重新登录 → grants 保留，App 收到 login 事件

什么时候不一定需要 AuthKit ​

  • 你的 App 不需要知道当前用户是谁
  • 你只使用 ModelKit 做模型调用，不涉及用户身份
  • 你不需要跨设备关联用户

下一步看什么 ​