Composio Connected Accounts API 完全指南：用 TypeScript 管理用户第三方服务连接
发布时间：2026/9/12 1:44:44 作者：尧图编辑部 阅读量：1,286
Composio Connected Accounts API 完全指南用 TypeScript 管理用户第三方服务连接【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio导读Connected Accounts连接账户是 Composio 中承载用户与外部服务toolkit之间认证关系的核心实体它存储 OAuth Token、API Key 等访问凭据。本文以ts/docs/api/connected-accounts.md为主干结合 ConnectedAccounts 类源码、AuthScheme 源码 与 官方示例系统讲解composio.connectedAccounts全部公开方法的调用方式、12 种认证方案的配置细节、连接状态机与多连接管理策略读完即可在真实 Agent 应用中完成创建连接 → 用户授权 → 等待激活 → 执行工具的完整闭环。认识 ConnectedAccountsAgent 与外部服务的凭据枢纽在 Composio 的架构中Agent 要真正把意图变成行动就必须调用 Gmail、GitHub、Slack 等外部服务的工具而这些工具无一例外需要用户的授权凭据。ConnectedAccounts类就是管理这些凭据的统一入口每条连接账户对应一个用户userId与一个外部服务toolkit连接账户内部保存访问令牌及访问该服务所需的其他信息SDK 通过 ConnectedAccounts.ts 暴露list、link、initiate、waitForConnection、get、delete、refresh、updateStatus、enable、disable等一整套生命周期方法。从源码结构看ConnectedAccounts类在构造时注入底层ComposioClient并对每一次调用做了遥测埋点telemetry.instrument(this, ConnectedAccounts)因此所有方法都支持通过可选的requestOptions透传signal实现请求取消withCancellation包装。这意味着你可以把任何一个连接操作挂接到 AbortController 上。连接账户的查询与检索list(query?)按筛选条件列出连接账户list用于按条件批量查询连接账户支持按用户、按 toolkit、按认证配置、按状态组合过滤// 列出所有连接账户 const allAccounts await composio.connectedAccounts.list(); // 列出指定用户的连接账户 const userAccounts await composio.connectedAccounts.list({ userIds: [user123], }); // 列出指定 toolkit 的连接账户 const githubAccounts await composio.connectedAccounts.list({ toolkitSlugs: [github], });参数与返回值queryConnectedAccountListParams可选的过滤参数返回值PromiseConnectedAccountListResponse——一个分页列表抛错ValidationError当 query 未通过 Zod 模式校验时。在 ConnectedAccounts.ts 的实现中list会先用ConnectedAccountListParamsSchema.safeParse(query)做运行时校验再把 camelCase 的 SDK 参数转换为 wire 格式snake_case下发给底层 client最后经transformConnectedAccountListResponse把响应重新规范化为 SDK 类型。因此传参时务必保证字段名、类型与类型定义一致否则会直接抛ValidationError。get(nanoid)按 ID 获取单个连接账户// 根据连接账户 ID 获取详情 const account await composio.connectedAccounts.get(conn_abc123); console.log(account.status); // 例如 ACTIVE console.log(account.toolkit.slug); // 例如 github参数与返回值nanoidstring连接账户的唯一标识返回值PromiseConnectedAccountRetrieveResponse抛错连接账户不存在或 API 出错时抛Error。建立连接link 与 initiate 双路径Composio 提供了两条创建连接的路径分别面向托管式 OAuth 授权页与手动传入凭据两种场景。link(userId, authConfigId, options?)生成 Composio Connect 托管授权链接link为指定用户和 auth config 创建一条 Composio Connect Link返回一个外部链接用户通过该链接在 Composio 托管的认证流程中完成授权// 创建连接请求并把用户重定向到 redirect URL const connectionRequest await composio.connectedAccounts.link(user_123, auth_config_123); const redirectUrl connectionRequest.redirectUrl; console.log(Visit: ${redirectUrl} to authenticate your account); // 等待连接建立 const connectedAccount await connectionRequest.waitForConnection();// 携带回调 URL 创建连接请求 const connectionRequest await composio.connectedAccounts.link(user_123, auth_config_123, { callbackUrl: https://your-app.com/callback }); const redirectUrl connectionRequest.redirectUrl; console.log(Visit: ${redirectUrl} to authenticate your account); // 也可以直接在 ConnectedAccounts 上等待 const connectedAccount await composio.connectedAccounts.waitForConnection(connectionRequest.id);参数与返回值userIdstring外部用户 IDauthConfigIdstring要连接到的 auth config IDoptionsCreateConnectedAccountLinkOptions可选配置其中callbackUrl是用户完成连接后跳转的 URL返回值PromiseConnectionRequest——携带redirectUrl的连接请求对象抛错ValidationErroroptions 校验失败ComposioFailedToCreateConnectedAccountLink链接创建失败。从 link 的实现 可以看到几个关键行为创建前会执行一次预检按userIds authConfigIds ACTIVE 状态调用list若已存在活动连接且未开启allowMultiple直接抛ComposioMultipleConnectedAccountsError避免静默产生重复连接请求体支持callbackUrl、alias人类可读别名需在同一项目内对 userId toolkit 唯一以及实验性的experimental块用于 SHARED 连接与 ACL服务端对 PRIVATE 连接拒绝 ACL 时会抛ComposioAclOnlyForSharedError其余失败统一包装为ComposioFailedToCreateConnectedAccountLink返回的ConnectionRequest初始状态为INITIATED。initiate(userId, authConfigId, options?)手动传参创建连接initiate通过手动提交参数创建连接账户并返回一个连接请求对象随后可用waitForConnection等待连接就绪// OAuth 类 auth config无需额外参数 const oauthConnection await composio.connectedAccounts.initiate(user_123, auth_config_123, { callbackUrl: https://myapp.com/auth/callback, }); // 需要额外参数的 OAuth config如 Zendesk、PostHog const zendeskConnection await composio.connectedAccounts.initiate(user_123, zendesk_auth_config, { config: AuthScheme.OAuth2({ subdomain: yout_subdomain_here }) }); // API Key 类 auth config需要额外参数 const apiKeyConnection await composio.connectedAccounts.initiate(user_123, auth_config_456, { config: AuthScheme.ApiKey({ api_key: your_api_key_here, }), }); // Basic Auth 类 auth config需要用户名/密码 const basicAuthConnection await composio.connectedAccounts.initiate( user_123, auth_config_789, { config: AuthScheme.Basic({ username: your_username, password: your_password, }), } ); // redirectUrl 是 OAuth 流程中应把用户重定向去完成认证的地址 console.log(oauthConnection.redirectUrl); // 等待用户完成连接 const connectedAccount await oauthConnection.waitForConnection();参数与返回值userIdstring连接账户所属用户 IDauthConfigIdstring连接账户所属 auth config IDoptionsCreateConnectedAccountOptionsconfig通过AuthScheme辅助函数构造的连接配置callbackUrlOAuth 认证完成后的跳转 URL另有源码中定义的allowMultiple是否允许多连接与alias连接别名返回值PromiseConnectionRequest。重要initiate 的迁移提示。在 ConnectedAccounts.ts 源码注释 中明确标注对于 Composio 托管的 OAuthOAuth1、OAuth2、DCR_OAUTHinitiate底层包装的旧版POST /api/v3/connected_accounts端点正在退役——新组织于 2026-05-08、其余组织于 2026-07-03 切换。切换后initiate对Composio 托管 可重定向 OAuth 方案这一组合会抛ComposioLegacyConnectedAccountsEndpointRetiredError。服务端还会通过响应头的Deprecation字段RFC 9745发出一次性进程级警告。建议对 Composio 托管 OAuth 一律改用link()——它适用于所有可重定向方案且返回结构与initiate一致。自定义 OAuth 应用与非 OAuth 方案API Key、Bearer Token、Basic Auth不受影响继续使用initiate即可。waitForConnection(connectedAccountId, timeout?)等待连接变为 ACTIVEwaitForConnection会持续轮询 Composio API直到连接进入 ACTIVE 终态、进入错误终态或超时// 使用默认超时60 秒 const connectedAccount await composio.connectedAccounts.waitForConnection(conn_123abc); // 使用自定义超时2 分钟 const connectedAccount await composio.connectedAccounts.waitForConnection(conn_123abc, 120000);参数与返回值connectedAccountIdstring要等待的连接账户 IDtimeoutnumber最大等待毫秒数默认 60 秒返回值PromiseConnectedAccountRetrieveResponse抛错ComposioConnectedAccountNotFoundError连接账户不存在ConnectionRequestFailedError连接进入 failed、expired 或 deleted 状态ConnectionRequestTimeoutError超时未完成。从 ConnectionRequest.ts 可以看到轮询的底层机制先做一次快速检查若已 ACTIVE 直接返回若处于 FAILED/EXPIRED/REVOKED 终态立即抛ConnectionRequestFailedError若 404 则抛ComposioConnectedAccountNotFoundError随后以1000ms 间隔循环轮询直到Date.now() - start timeout才抛ConnectionRequestTimeoutError。返回的ConnectionRequest对象还带toJSON()/toString()便于日志输出。官方示例 README 还演示了用try/catch分别捕获ConnectionRequestTimeoutError与ConnectionRequestFailedError的推荐写法。连接账户的生命周期管理删除、刷新与启停delete(nanoid)永久删除连接// 删除一个连接账户 await composio.connectedAccounts.delete(conn_abc123);nanoidstring要删除的连接账户 ID返回值PromiseConnectedAccountDeleteResponse抛错账户不存在或无法删除时抛Error。该操作不可撤销并会吊销与该账户关联的访问令牌见 源码注释。refresh(nanoid)刷新认证凭据// 刷新连接账户的凭据 const refreshedAccount await composio.connectedAccounts.refresh(conn_abc123);nanoidstring要刷新的连接账户 ID返回值PromiseConnectedAccountRefreshResponse抛错账户不存在或凭据无法刷新时抛Error。当 OAuth Token 已过期或即将过期时refresh会尝试刷新令牌。源码还支持ConnectedAccountRefreshOptions含redirectUrl与validateCredentials两个可选字段分别对应query_redirect_url与validate_credentials参数用于在刷新后重定向并校验凭据有效性。updateStatus(nanoid, params)更新连接状态// 更新连接账户状态 const updatedAccount await composio.connectedAccounts.updateStatus(conn_abc123, { enabled: true, });nanoidstring连接账户 IDparamsConnectedAccountUpdateStatusParams{ enabled: boolean }返回值PromiseConnectedAccountUpdateStatusResponse。enable(nanoid) 与 disable(nanoid)快捷启停// 启用一个连接账户 const enabledAccount await composio.connectedAccounts.enable(conn_abc123); // 禁用一个连接账户 const disabledAccount await composio.connectedAccounts.disable(conn_abc123);两者分别是updateStatus(nanoid, { enabled: true })与updateStatus(nanoid, { enabled: false })的语法糖见 ConnectedAccounts.ts。updateStatus亦可携带reason说明禁用原因。补充源码中还有实验性的updateAcl(nanoid, params)仅对 SHARED 连接生效对 PRIVATE 连接抛ComposioAclOnlyForSharedError与update(nanoid, params)前者用于按用户维度控制共享连接的使用权限后者等价于带校验的updateStatus。核心类型速查ConnectedAccountListParamsinterface ConnectedAccountListParams { authConfigIds?: string[]; // 按 auth config ID 过滤 cursor?: string; // 分页游标 labels?: string[]; // 按标签过滤 limit?: number; // 限制返回数量 orderBy?: string; // 排序字段源码中限定为 created_at | updated_at statuses?: string[]; // 按状态过滤 toolkitSlugs?: string[]; // 按 toolkit slug 过滤 userIds?: string[]; // 按用户 ID 过滤 }在 connectedAccounts.types.ts 中statuses被ConnectedAccountStatusSchema约束为枚举INITIALIZING、INITIATED、ACTIVE、FAILED、EXPIRED、INACTIVE、REVOKED此外还有实验性的accountTypePRIVATE | SHARED | ALL缺省只返回 PRIVATE。ConnectedAccountListResponseinterface ConnectedAccountListResponse { items: ConnectedAccountRetrieveResponse[]; // 连接账户列表 nextCursor: string | null; // 下一页游标 totalPages: number; // 总页数 }ConnectedAccountRetrieveResponseinterface ConnectedAccountRetrieveResponse { id: string; // 连接账户 ID status: string; // 状态如 ACTIVE、PENDING statusReason: string | null; // 状态原因 userId: string; // 用户 ID toolkit: { // 关联的 toolkit id: string; // Toolkit ID slug: string; // Toolkit slug name: string; // Toolkit 名称 }; authConfig: { // 关联的 auth config id: string; // Auth config ID authScheme: string; // 认证方案如 oauth2 isComposioManaged: boolean; // 是否由 Composio 托管 isDisabled: boolean; // 是否被禁用 }; isDisabled: boolean; // 连接账户是否被禁用 meta: Recordstring, unknown; // 附加元数据 createdAt: string; // 创建时间戳 updatedAt: string; // 最后更新时间戳 testRequestEndpoint: string | null; // 用于测试连接的端点 }从响应转换器 connectedAccounts.ts 的实现看SDK 会把 wire 层的 snake_case 字段auth_scheme、is_composio_managed、status_reason、created_at等统一转换为 camelCase并用ConnectionDataSchema安全解析state字段——遇到暂不支持的 auth scheme 时只会告警并忽略该字段不会让整个请求失败。CreateConnectedAccountOptionsinterface CreateConnectedAccountOptions { config?: ConnectionData; // 使用 AuthScheme 辅助函数构造的连接配置 callbackUrl?: string; // 认证完成后的跳转 URL // 源码中另有allowMultiple?: boolean; alias?: string; }CreateConnectedAccountLinkOptionsinterface CreateConnectedAccountLinkOptions { callbackUrl?: string; // 用户完成连接后跳转的 URL // 源码中另有alias?: string; allowMultiple?: boolean; experimental?: {...} }回调 URL 的语义见 类型定义注释连接成功时会在回调 URL 上追加查询参数statussuccess失败时追加statusfailed。ConnectedAccountUpdateStatusParamsinterface ConnectedAccountUpdateStatusParams { enabled: boolean; // 账户是否应被启用 }AuthScheme 辅助函数12 种认证方案全解析AuthScheme类AuthScheme.ts为每一种认证方案提供类型安全的静态工厂函数返回经过 Zod 校验的ConnectionData对象。连接状态规则OAuth2、OAuth1 与 Composio Link 方案初始为INITIALIZING其余方案初始为ACTIVE。OAuth2— 无需额外参数重定向流程若传入access_token则状态直接为ACTIVEToken 导入场景await composio.connectedAccounts.initiate(userId, authConfigId);OAuth1— 无需额外参数await composio.connectedAccounts.initiate(userId, authConfigId);API Key— 需要api_keyawait composio.connectedAccounts.initiate(userId, authConfigId, { config: AuthScheme.ApiKey({ api_key: your_api_key, }), });Basic Auth— 需要username与passwordawait composio.connectedAccounts.initiate(userId, authConfigId, { config: AuthScheme.Basic({ username: your_username, password: your_password, }), });Bearer Token— 需要tokenawait composio.connectedAccounts.initiate(userId, authConfigId, { config: AuthScheme.BearerToken({ token: your_bearer_token, }), });Google Service Account— 需要credentials_jsonawait composio.connectedAccounts.initiate(userId, authConfigId, { config: AuthScheme.GoogleServiceAccount({ credentials_json: your_credentials_json, }), });Basic with JWT— 需要username、password与 JWTawait composio.connectedAccounts.initiate(userId, authConfigId, { config: AuthScheme.BasicWithJwt({ username: your_username, password: your_password, jwt: your_jwt_token, }), });Bill.com Auth— 需要sessionId与devKeyawait composio.connectedAccounts.initiate(userId, authConfigId, { config: AuthScheme.BillcomAuth({ sessionId: your_session_id, devKey: your_dev_key, }), });Composio Link— 无需额外参数await composio.connectedAccounts.initiate(userId, authConfigId, { config: AuthScheme.ComposioLink(), });Cal.com Auth— 无需额外参数await composio.connectedAccounts.initiate(userId, authConfigId, { config: AuthScheme.CalcomAuth(), });Snowflake— 无需额外参数await composio.connectedAccounts.initiate(userId, authConfigId, { config: AuthScheme.Snowflake(), });No Auth— 无需额外参数await composio.connectedAccounts.initiate(userId, authConfigId, { config: AuthScheme.NoAuth(), });源码实现细节AuthScheme.OAuth2的val.status会根据是否传入access_token自动判定——有 token 视为 Token 导入ACTIVE无 token 视为重定向流程INITIALIZINGOAuth1则要求oauth_token与oauth_token_secret同时存在才判定为ACTIVE见 AuthScheme.ts。此外 connectedAccountAuthStates.types.ts 中还定义了面向特定服务商的附加字段如 Zendesk/PostHog 的subdomain、Shopify 的shop、Salesforce 的instanceEndpoint等以及S2S_OAUTH2、DCR_OAUTH、SERVICE_ACCOUNT、SAML等更多底层方案 schema需要时可直接查阅该文件。多连接管理allowMultiple 与默认去重策略默认行为同一 auth config 仅允许一个活动连接默认情况下Composio 禁止同一用户对同一 auth config 建立多个连接账户以避免冲突并保证行为一致。若用户已存在该 auth config 的活动连接再次创建会抛ComposioMultipleConnectedAccountsError// 用户已有连接时会抛错 try { await composio.connectedAccounts.initiate(user_123, auth_config_123); } catch (error) { if (error instanceof ComposioMultipleConnectedAccountsError) { console.log(User already has a connected account for this auth config); } }这一守卫在 initiate 与 link 的实现 中都是先以userIds authConfigIds ACTIVE 状态做预检查询实现的。开启多连接allowMultiple: true如果应用确实需要同一 auth config 对应多个连接例如让一个用户同时连接多个 GitHub 账号传入allowMultiple即可// 允许创建多个连接 const connection await composio.connectedAccounts.initiate(user_123, auth_config_123, { allowMultiple: true, });开启后同一用户与 auth config 允许存在多个活动连接SDK 会输出一条[Warn:AllowMultiple]警告日志便于追踪该行为见 ConnectedAccounts.ts应用逻辑需要自行管理具体使用哪条连接执行操作。注意开启多连接需要应用侧额外的处理逻辑来区分与选择连接请谨慎评估后再启用。实战完整的连接生命周期示例综合以上内容一个典型的GitHub 连接 工具调用流程如下可对照 ts/examples/connected-accounts 中的toolkit-authorize.ts示例import { Composio, AuthScheme, ComposioMultipleConnectedAccountsError } from composio-core; const composio new Composio({ apiKey: process.env.COMPOSIO_API_KEY }); // 1. 生成托管授权链接推荐用于 Composio 托管 OAuth const connectionRequest await composio.connectedAccounts.link( user_123, github_auth_config, { callbackUrl: https://your-app.com/callback } ); console.log(请访问授权页: ${connectionRequest.redirectUrl}); // 2. 等待用户完成授权默认 60s可自定义超时 try { const account await connectionRequest.waitForConnection(120000); console.log(连接成功:, account.id, account.toolkit.slug); } catch (error) { if (error instanceof ConnectionRequestTimeoutError) { console.error(连接超时请重试); } else if (error instanceof ConnectionRequestFailedError) { console.error(连接失败:, error.message); } } // 3. 需要手动注入凭据时使用 initiate AuthScheme const apiKeyConn await composio.connectedAccounts.initiate(user_123, some_api_auth_config, { config: AuthScheme.ApiKey({ api_key: process.env.SERVICE_API_KEY! }), }); // 4. 查询、刷新、启停、删除 const activeGithub await composio.connectedAccounts.list({ userIds: [user_123], toolkitSlugs: [github], statuses: [ACTIVE], }); await composio.connectedAccounts.refresh(activeGithub.items[0].id); await composio.connectedAccounts.disable(activeGithub.items[0].id); await composio.connectedAccounts.enable(activeGithub.items[0].id); await composio.connectedAccounts.delete(activeGithub.items[0].id);运行前提TypeScript SDK 需要先安装依赖并设置COMPOSIO_API_KEY环境变量然后传入userId应用侧外部用户 ID与authConfigId在 Composio 控制台或通过 Auth Configs API 预先配置。扩展阅读路径类完整实现含updateAcl、update等实验性方法ts/packages/core/src/models/ConnectedAccounts.ts认证方案工厂ts/packages/core/src/models/AuthScheme.ts连接状态机与轮询实现ts/packages/core/src/models/ConnectionRequest.ts全部类型定义与 Zod 校验 schemats/packages/core/src/types/connectedAccounts.types.ts、ts/packages/core/src/types/connectedAccountAuthStates.types.ts响应规范化转换器ts/packages/core/src/utils/transformers/connectedAccounts.ts可直接运行的示例工程ts/examples/connected-accounts对应的 Python SDK 文档与测试python/docs/development.md、python/tests/test_connected_accounts.py相关产品概念docs/api-overviews/connected-accounts.mdx【免费下载链接】composioComposio powers 1000 toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.项目地址: https://gitcode.com/GitHub_Trending/co/composio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
尧图网站开发 