Composio 项目 API Key 权限完全指南：Scoped Key 权限域、Proxy Execute 与 401 排障

Composio 项目 API Key 权限完全指南Scoped Key 权限域、Proxy Execute 与 401 排障【免费下载链接】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 中Project API Key 是调用后端 API工具执行、会话创建、Proxy Execute 等的身份凭证。本文以官方知识库文档 platform-project-api-key-permissions.md 为主体结合权限参考文档与 Python SDK 源码系统讲解 Scoped Project API Key 的权限模型、三大高频权限报错场景Proxy Execute、Session 创建、工具执行的根因与修复方法以及泛化 401 Invalid API key的成因。读完你不仅能正确创建带权限的 Key还能在权限被拒时快速定位是哪个权限域配置不当。一、什么是 Project API Key 与 Scoped KeyProject API Key 是 Composio 项目级 API 凭证用于在x-api-key请求头中对后端如 v3 / v3.1 API进行身份认证。默认创建的 Project API Key 拥有项目级完整权限full access。而Scoped Project API Key作用域受限的 Key允许你在创建时选择该 Key 可以访问的项目资源子集——例如只允许执行工具、只允许读取日志、或只允许管理连接账户。适用场景是某个 Key 只需要项目的一部分能力时用最小权限原则收敛暴露面。两个关键约束来自 project-api-key-permissions.mdx权限在创建时确定之后无法修改。需要调整权限时只能新建一个 Key并把应用轮换到新 Key 上。默认 Project API Key 保持完整访问权限只有 Scoped Key 才会应用本页所述的权限域与访问级别。二、在 Dashboard 创建 Scoped API Key创建流程官方步骤打开 Composio Dashboard。选择Platform。选择你的项目。进入Settings。打开API Keys标签页。点击Create API Key然后按下文所述的权限域Permission areas与访问级别Access levels进行勾选。创建时务必先想清楚该 Key 将承担哪些调用因为创建后权限不可再调整。三、访问级别Access LevelsScoped Key 的每个权限域都对应一个访问级别访问级别允许的行为No access无访问该 Key 无法使用该权限域下的任何路由Read only只读该 Key 可以使用该权限域下的读路由Write only只写该 Key 可以使用该权限域下的写路由Read and write读写该 Key 可以使用该权限域下的读写路由两点容易误判的细节判断依据是路由的实际语义而非 HTTP 方法部分读路由使用POST因为请求体携带筛选条件或查找输入例如POST /api/v3.1/logs/tool_execution、POST /api/v3.1/tools/execute/{tool_slug}/input都属于读类路由。v3 与 v3.1 同形路由只列一次当 v3 和 v3.1 暴露相同的路由形态时官方文档只列出一个代表性版本版本特有路由会单独列出。四、权限域总览Permission Areas官方参考文档将权限划分为 10 个域各自的可用级别如下权限域可用级别覆盖内容Auth configs认证配置No access / Read only / Write only / Read and write查看与修改认证配置Connected accounts连接账户No access / Read only / Write only / Read and write查看与管理连接账户Tools工具No access / Read only查看工具定义、输入、作用域与版本Tool execution工具执行No access / Write only执行预定义的 Composio 工具Proxy execute代理执行No access / Write only通过原始代理路径对连接账户发起请求Toolkits工具包No access / Read only / Write only / Read and write查看与安装工具包Triggers触发器No access / Read only / Write only / Read and write查看触发器类型、管理触发器实例、订阅触发器事件WebhooksNo access / Read only / Write only / Read and write查看与管理 webhook 端点及订阅Observability可观测性No access / Read only查看执行日志与项目用量汇总Sessions会话No access / Read only / Write only / Read and write创建与操作会话及 MCP 服务器注意Proxy execute 与 Tool execution 是两个独立权限域。Proxy execute 只有在你的应用确实需要走原始代理路径调用连接账户 API 时才需要授予。五、场景一Proxy Execute 需要显式授予 Proxy execute 权限来自知识库原文在 Dashboard 中创建一个带作用域的 Project API Key并在创建 Key 时启用Proxy Execute然后再调用 v3.1 Proxy Execute API。如果请求被拒绝请先核对 Key 的权限域再去排查 provider 连接问题。若仍需联系 Composio 支持请使用正确作用域 Key 产生的全新 request ID。5.1 Proxy Execute 是什么Proxy Execute 允许你通过会话对某个 toolkit 的任意 HTTP 端点发起请求由 Composio 在服务端注入认证信息OAuth token、API key、basic auth 等你的代码从不接触原始凭证。详细用法见 proxy-execute.mdxfrom composio import Composio composio Composio(api_keyyour_api_key) session composio.create(user_123, toolkits[github]) response session.proxy_execute( toolkitgithub, endpoint/repos/composiohq/composio/issues/1, methodGET, parameters[ {name: Accept, value: application/vnd.github.v3json, in: header}, ], ) print(response[status]) print(response[data])5.2 底层端点与源码佐证Proxy execute 权限域覆盖两个写路由访问方法端点WritePOST/api/v3.1/tools/execute/proxyWritePOST/api/v3/tool_router/session/{session_id}/proxy_execute在 Python SDK 中ToolRouterSession.proxy_execute(...)定义于 python/composio/core/models/tool_router_session.py最终调用proxy_execute_impl走代理执行路径参数包括toolkit、endpoint、method仅限GET/POST/PUT/DELETE/PATCH、body、parameters。5.3 排障路径症状POST /api/v3.1/tools/execute/proxy返回 401 或权限错误即使连接账户本身状态正常。根因优先排查 Key先确认发起请求的 Key 是否为 Scoped Key、是否勾选了Proxy execute Write only。不要一上来就怀疑 provider 连接token 过期、scope 不足等。修复新建一个勾选了 Proxy execute 权限的 Project API Key或改用默认全权限 Key。联系支持前请用正确作用域 Key 重新发起一次请求并附带该请求的 request ID便于后端定位。六、场景二Tool Router 会话创建需要 Sessions 写权限来自知识库原文对于 Scoped Project API Key通过composio.sessions.create(...)或POST /api/v3.1/tool_router/session创建会话需要Sessions 权限且为 write 或 read/write 级别。一个 Key 即使能成功调用GET /api/v3.1/toolkits只授予了 Toolkits 读权限也可能无法创建会话SDK 可能把这种作用域权限拒绝表现为泛化的 401Invalid API key。请新建一个 Sessions 设为 Read and write 的 Project API Key或改用合适的全权限 Key然后重试会话创建。6.1 SDK 调用到端点的映射从源码看python/composio/sdk.py 将composio.sessions暴露为ToolRouter实例并提供composio.create/composio.use快捷方式composio.sessions.create(...)正是官方推荐的会话创建入口composio.tool_router为旧名已标记 deprecated。其底层对应POST /api/v3.1/tool_router/session写路由因此必须拥有 Sessions 权限域的写能力。6.2 典型误判权限检查是逐权限域的GET /api/v3.1/toolkits只验证Toolkits 读权限通过它只能说明该域配置正确与 Sessions 域毫无关系。这正是能列出 toolkit 却建不了会话这一矛盾现象的根源。6.3 修复步骤确认当前 Key 的 Sessions 访问级别若为 No access 或 Read only新建 Key 时将 Sessions 设为Read and write或至少 Write only用新 Key 重试composio.sessions.create(...)或POST /api/v3.1/tool_router/session。Sessions 权限域还覆盖 MCP 服务器管理、MCP runtime 传输与 tool router MCP 传输详见第七节完整路由表。七、场景三工具执行需要 Tool execution 写权限来自知识库原文对于 Scoped Project API Keycomposio.tools.execute()以及工具执行 API 需要Tool execution 设置为 Write 或 Read and write。缺少该权限的 Key 即使存在且处于 active 状态也可能表现为泛化的 401Invalid API key。请新建正确作用域的 Project API Key 或使用合适的全权限 Key 后重试当前 API 可能返回泛化权限错误需从 Key 的权限本身诊断该行为。7.1 底层调用链composio.tools.execute(slug, arguments, ...)python/composio/core/models/tools.py经由_execute_tool调用self._client.without_retries.tools.execute(...)python/composio/core/models/tools.py对应POST /api/v3.1/tools/execute/{tool_slug}。值得注意的实现细节工具执行被视为非幂等写操作SDK 显式禁用重试without_retries以避免读超时后的静默重试造成副作用重复——这也意味着一旦权限被拒失败会直接冒泡到调用方。Tool execution 权限域覆盖以下写路由访问方法端点WritePOST/api/v3.1/tools/execute/{tool_slug}WritePOST/api/v3/files/upload/requestWritePOST/api/v3/files/upload/responseWriteGET/api/v3/files/list注意查看工具定义Tools 域只读与执行工具Tool execution 域只写是两个独立的权限域。即使你的 Key 能成功枚举工具GET /api/v3.1/tools也可能因为缺少 Tool execution 权限而无法真正执行。7.2 修复步骤在 Dashboard 中核对发起调用的 Key 是否勾选了Tool execution Write only或 Read and write若未勾选新建正确作用域的 Key 或用全权限 Key 重试若 Key 已正确配置仍失败再转而排查连接账户状态token 过期、scope 不足等。八、为什么会出现泛化 401 Invalid API key知识库文档两次强调同一现象当 Scoped Key 缺少对应权限时服务端可能返回泛化的401 Invalid API key即使该 Key 真实存在且处于 active 状态。这意味着不要把 401 一律等同于Key 无效/被吊销排障顺序应为先核对 Key 的权限域配置 → 再排查 provider 连接对于自己管理的应用建议在代码中记录请求使用的 Key 标识如 Key 前缀或 request ID便于区分凭证无效与权限不足两类 401。九、权限域与路由完整映射排障速查以下为官方参考文档中的完整路由表供按权限域逐一核对v3 与 v3.1 同形路由仅列一次。Auth configs认证配置访问方法端点ReadGET/api/v3/auth_configsReadGET/api/v3/auth_configs/{nanoid}WritePOST/api/v3/auth_configsWritePATCH/api/v3/auth_configs/{nanoid}WriteDELETE/api/v3/auth_configs/{nanoid}WritePATCH/api/v3/auth_configs/{nanoid}/{status}Connected accounts连接账户访问方法端点ReadGET/api/v3/connected_accountsReadGET/api/v3/connected_accounts/{nanoid}WritePOST/api/v3/connected_accountsWritePOST/api/v3/connected_accounts/linkWritePATCH/api/v3/connected_accounts/{nanoid}WritePATCH/api/v3/connected_accounts/{nanoid}/statusWritePOST/api/v3/connected_accounts/{nanoid}/refreshWriteDELETE/api/v3/connected_accounts/{nanoid}WritePOST/api/v3.1/connected_accounts/{nanoid}/revokeTools查看工具定义访问方法端点ReadGET/api/v3.1/toolsReadGET/api/v3.1/tools/enumReadGET/api/v3.1/tools/{tool_slug}ReadGET/api/v3/tools/{tool_slug}/get_latest_versionReadGET/api/v3.1/tools/scopes/requiredReadGET/api/v3.1/tools/get_scopes_requiredReadPOST/api/v3.1/tools/execute/{tool_slug}/inputToolkits查看与安装工具包访问方法端点ReadGET/api/v3/toolkitsReadGET/api/v3/toolkits/{slug}ReadGET/api/v3/toolkits/categoriesReadGET/api/v3/toolkits/changelogWritePOST/api/v3/toolkits/multiTriggers触发器realtime 路由由 SDK 的triggers.subscribe()与 CLI 调用访问方法端点ReadGET/api/v3/triggers_typesReadGET/api/v3/triggers_types/{slug}ReadGET/api/v3/triggers_types/list/enumReadGET/api/v3/trigger_instances/activeReadGET/api/v3/cli/realtime/credentialsReadPOST/api/v3/cli/realtime/authReadGET/api/v3/internal/sdk/realtime/credentialsReadPOST/api/v3/internal/sdk/realtime/authWritePOST/api/v3/trigger_instances/{slug}/upsertWritePATCH/api/v3/trigger_instances/manage/{triggerId}WriteDELETE/api/v3/trigger_instances/manage/{triggerId}Webhooks访问方法端点ReadGET/api/v3/webhook_endpointsReadGET/api/v3/webhook_endpoints/{nano_id}ReadGET/api/v3/webhook_endpoints/schemaReadGET/api/v3/webhook_subscriptionsReadGET/api/v3/webhook_subscriptions/{id}ReadGET/api/v3/webhook_subscriptions/event_typesWritePOST/api/v3/webhook_endpointsWritePOST/api/v3/webhook_endpoints/{nano_id}WritePATCH/api/v3/webhook_endpoints/{nano_id}WriteDELETE/api/v3/webhook_endpoints/{nano_id}WritePOST/api/v3/webhook_subscriptionsWritePATCH/api/v3/webhook_subscriptions/{id}WriteDELETE/api/v3/webhook_subscriptions/{id}WritePOST/api/v3/webhook_subscriptions/{id}/rotate_secretObservability可观测性读取执行日志与项目用量访问方法端点ReadPOST/api/v3.1/logs/tool_executionReadGET/api/v3.1/logs/tool_execution/{id}ReadPOST/api/v3.1/project/usage/{entity_type}ReadPOST/api/v3.1/project/usage/summarySessions会话与 MCP覆盖 MCP 服务器管理、MCP runtime 传输与 tool router MCP 传输访问方法端点ReadGET/api/v3/mcp/serversReadGET/api/v3/mcp/{id}ReadGET/api/v3/mcp/app/{app_key}ReadGET/api/v3/mcp/servers/{server_id}/instancesReadGET/tool_router/{session_id}/mcpReadGET/api/v3.1/tool_router/session/{session_id}ReadGET/api/v3/tool_router/session/{session_id}/toolkitsReadGET/api/v3.1/tool_router/session/{session_id}/toolsReadGET/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/itemsReadGET/api/v3.1/tool_router/session/{session_id}/config_historyWritePOST/api/v3/mcp/serversWritePOST/api/v3/mcp/servers/generateWritePOST/api/v3/mcp/servers/customWritePATCH/api/v3/mcp/{id}WriteDELETE/api/v3/mcp/{id}WritePOST/api/v3/mcp/servers/{server_id}/instancesWriteDELETE/api/v3/mcp/servers/{server_id}/instances/{instance_id}WritePOST/api/v3/mcp/{server_id}/{transport}WriteDELETE/api/v3/mcp/{server_id}/{transport}WritePOST/tool_router/{session_id}/mcpWriteDELETE/tool_router/{session_id}/mcpWritePOST/api/v3.1/tool_router/sessionWritePOST/api/v3.1/tool_router/session/{session_id}/executeWritePOST/api/v3.1/tool_router/session/{session_id}/execute_metaWritePOST/api/v3/tool_router/session/{session_id}/linkWritePOST/api/v3.1/tool_router/session/{session_id}/searchWritePATCH/api/v3.1/tool_router/session/{session_id}WritePOST/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/upload_urlWritePOST/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/download_urlWritePOST/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/deleteWritePOST/api/v3.1/tool_router/session/{session_id}/attach十、排障清单与最佳实践权限先行任何 401/权限错误先确认调用 Key 是否为 Scoped Key、对应权限域与级别是否满足路由要求再排查 provider 连接。三个最容易踩坑的权限域是Proxy executeWrite、SessionsWrite/Read and write、Tool executionWrite/Read and write。权限不可变Scoped Key 的权限在创建时固化调整权限 新建 Key 轮换。生产环境建议为不同职责代理执行、会话管理、工具执行、只读监控分别创建最小权限 Key。区分读与执行能GET /api/v3.1/toolsTools 读不代表能POST /api/v3.1/tools/execute/{tool_slug}Tool execution 写能列 toolkits 不代表能建会话Sessions 写。泛化 401 的应对SDK 可能把作用域权限不足表现为401 Invalid API key请基于 Key 的权限配置诊断而非直接判定 Key 失效。保留 request ID联系支持时使用正确作用域 Key 重新发起请求并提供该请求的 request ID。延伸阅读权限完整参考docs/content/reference/authenticating-to-composio/project-api-key-permissions.mdxProxy Execute 用法详解docs/content/docs/extending-sessions/proxy-execute.mdxAPI v3.1 变更说明工具端点默认 latest 版本docs/content/changelog/04-08-26-v31-api.mdxPython SDK 会话入口python/composio/sdk.py工具执行实现禁用重试python/composio/core/models/tools.py会话代理执行实现python/composio/core/models/tool_router_session.py【免费下载链接】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），仅供参考