Composio Dashboard 指南：Platform Auth Configs 创建、Playground 测试连接与应用用户连接

Composio Dashboard 指南Platform Auth Configs 创建、Playground 测试连接与应用用户连接【免费下载链接】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本篇技术指南基于 Composio 官方知识库文档《Manage Platform auth configs》dashboard-auth-configs-navigation.md展开聚焦 Platform 控制台中最容易被忽略的三个操作环节从选定 Platform 项目创建 Auth Config、在 Auth Config 上使用Connect Account建立 Playground 测试连接、以及通过Manage Config理解配置变更对未来认证行为的影响。读完本文你将掌握在 Composio Dashboard 中正确创建与管理认证配置的完整流程并清楚区分测试连接与生产应用用户连接之间的本质差异避免在集成阶段踩坑。从选定的 Platform 项目创建 Auth Config在 Composio Dashboard 中认证配置Auth Config是一切连接的基础。它是一个蓝图定义了某个 toolkit 在所有用户之间如何进行认证包括认证方式auth_scheme、工具可请求的 scope以及 Composio 用于运行 OAuth 或 token 流程的凭据见 auth-configs.mdx。操作路径创建流程位于 Dashboard 的Platform → Auth Configs → Create Auth Config具体步骤如下进入Platform页面确认当前选中的组织和项目Auth Config 归属于某个 Platform 项目跨项目不可复用打开Auth Configs列表页点击Create Auth Config选择目标toolkit以及该 toolkit 支持的认证方式当托管认证managed authentication可用时优先选择托管认证否则输入客户自有凭据customer-owned credentials。认证方式Auth Scheme选择依据 auth-configs.mdx 的说明Composio 支持四种认证方式实际可用的方式由所选 toolkit 自身决定方式含义适用场景OAUTH2OAuth 2.0 授权码流程用户通过托管授权页授权Composio 存储并自动刷新 access/refresh token大多数带用户账号的应用Gmail、GitHub、Slack、Notion 等默认使用 Composio 托管 OAuth 应用API_KEY用户提供静态 API key无 OAuth 流程key 随每次请求发送以 key 认证的服务如 SendGrid、Tavily、PostHogBEARER_TOKEN直接持有 bearer tokenComposio 以Authorization: Bearer token发送且不刷新需自行维护时效将已有 OAuth 或 server-to-server token 带入 Composio或签发长寿命 token 的应用BASIC用户名 密码的 HTTP Basic 认证使用 Basic Auth 的服务从源码角度看SDK 对认证方式的建模同样围绕这四类。在 TypeScript SDK 的 AuthScheme.ts 中定义了方案类型而 AuthConfigs.ts 中的authConfigs.create(my-toolkit, { authScheme: AuthSchemeTypes.API_KEY, ... })演示了通过 SDK 创建认证配置时如何显式指定authScheme。也就是说Dashboard 上的选择与 SDK/API 的auth_scheme字段一一对应你可以先用控制台验证流程再在代码中复现同样的配置。自定义 OAuth 的回调 URI对于自定义 OAuthcustom OAuth必须使用当前 Dashboard 显示的确切回调 URIcallback URI在 provider 应用中进行注册。不要从旧示例中复制回调 URI——回调地址可能随项目、环境或版本变化过期的 URI 会导致 OAuth 授权回调失败连接无法建立。项目归属与排障Auth Config 归属于且仅归属于一个 Platform 项目。如果在操作中发现某个配置或连接消失请先核对当前选中的组织organization与项目project确认无误后再重新创建而不是盲目重建。组织与项目是 Dashboard 中所有认证资源的顶层归属边界选错作用域是连接缺失最常见的原因。Connect Account它是 Playground 测试连接在 Auth Config 详情页上Connect Account按钮看起来像一个通用连接入口但它的实际语义需要特别注意这个控件用于认证当前项目的 Playground 用户仅供测试使用。关键区别在于Connect Account 不会要求输入应用用户 ID。它把连接绑定到项目自身预置的 Playground 用户身份上方便你在集成阶段快速验证某个 toolkit 的认证流程是否通畅。要为真实的应用用户建立连接必须通过 SDK 或 API 创建托管连接链接hosted connection link并在其中传入该应用稳定的user_id以及目标 Auth Config。为什么测试连接不能替代生产连接测试连接与生产连接在身份归属上完全不同。在 auth-configs.mdx 中说明当用户针对某个 Auth Config 完成认证时Composio 会创建一个 connected account 来存储该用户的 token并将其关联到你的用户 ID。也就是说连接的核心是用户身份 Auth Config这一对组合——Playground 用户与你的真实应用用户是两个不同的身份前者测试出来的结果不能代表后者的实际体验例如 scope 授权、token 刷新、多租户隔离等。通过 SDK 为真实用户创建连接在 TypeScript SDK 的 ConnectedAccounts.ts 中connectedAccounts.initiate()接收的第一个参数就是userIdconst connectionRequest await composio.connectedAccounts.initiate( user123, // 应用内稳定的用户 ID auth_abc123 // 目标 Auth Config 的 nanoid );从 ConnectedAccounts.ts 可以看到list()支持按userIds过滤说明一个用户可以在同一 Auth Config 下拥有连接记录而 ConnectedAccounts.ts 中镜像 initiate() 的守卫逻辑表明 SDK 会防止对同一用户静默创建多余连接除非显式开启allowMultiple选项。因此生产环境的标准姿势是在你的后端服务中调用 SDK/API 的 initiate / connection link 流程携带应用侧稳定user_id与目标 Auth Config将生成的托管连接链接交给用户完成授权。Dashboard 上的Connect Account仅作为开发期的 Playground 冒烟测试工具。Manage Config改变的是未来的认证行为Manage Config是 Auth Config 的管理入口用于查看并调整当前配置类型的各项属性启用状态enabled state配置当前是启用还是禁用凭据credentials托管应用的凭据或你自己的 OAuth client 与密钥可用的 scope 或执行设置该配置类型下工具可请求的权限范围与执行选项。修改凭据与 scope 的影响修改凭据或 scope不会追溯性地改变已有连接而是可能要求用户重新建立连接fresh connection变更才会反映到 provider 的授权grant中。原因在于已存储的 token 与 scope 授权是在连接创建时从 provider 获取的配置层面的改动无法反向改写 provider 侧已签发的授权。从 SDK 的实现可以印证这一点——AuthConfigs.ts 中的authConfigs.update()用于更新配置本身而 AuthConfigs.ts 中的updateStatus()、enable()、disable()则独立控制配置的启用/禁用状态这些操作都作用于配置层面而非已有连接的 token 层面。禁用或删除前的依赖检查在禁用disable或删除delete一个 Auth Config 之前务必检查依赖它的连接connections、会话sessions与触发器triggers连接依赖该配置建立的 connected account 将失去凭据来源会话正在使用这些连接的 agent 会话可能中断或降级触发器基于这些连接运行的 webhook/trigger 事件流可能停止。这也是为什么 Dashboard 的设计将启用/禁用与删除分开——禁用可以随时恢复删除则是不可逆操作。以 AuthConfigs.ts 中的authConfigs.delete(auth_abc123)为例删除前请确认所有依赖方已被妥善迁移或下线。关键要点速查创建在Platform → Auth Configs → Create Auth Config中选择 toolkit 与认证方式托管认证可用时优先选托管认证自定义 OAuth 务必注册 Dashboard 当前显示的确切回调 URI。归属Auth Config 属于单一 Platform 项目连接缺失时先核对组织与项目再决定是否重建。测试Connect Account绑定 Playground 用户仅用于测试不要求应用用户 ID。生产真实用户连接需通过 SDK/API 的 hosted connection link 流程携带稳定user_id与目标 Auth Config参见 ConnectedAccounts.ts。变更Manage Config中的凭据/scope 修改影响未来连接可能要求用户重新连接禁用/删除前先审查依赖的连接、会话与触发器。【免费下载链接】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），仅供参考