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 Key

Project 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

创建流程（官方步骤）：

1. 打开 Composio Dashboard。
2. 选择Platform。
3. 选择你的项目。
4. 进入Settings。
5. 打开API Keys标签页。
6. 点击Create API Key，然后按下文所述的权限域（Permission areas）与访问级别（Access levels）进行勾选。

创建时务必先想清楚该 Key 将承担哪些调用，因为创建后权限不可再调整。

三、访问级别（Access Levels）

Scoped 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 个域，各自的可用级别如下：

注意：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.mdx：

from composio import Composio composio = Composio(api_key="your_api_key") session = composio.create("user_123", toolkits=["github"]) response = session.proxy_execute( toolkit="github", endpoint="/repos/composiohq/composio/issues/1", method="GET", parameters=[ {"name": "Accept", "value": "application/vnd.github.v3+json", "in": "header"}, ], ) print(response["status"]) print(response["data"])

5.2 底层端点与源码佐证

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 修复步骤

1. 确认当前 Key 的 Sessions 访问级别；
2. 若为 No access 或 Read only，新建 Key 时将 Sessions 设为Read and write（或至少 Write only）；
3. 用新 Key 重试composio.sessions.create(...)或POST /api/v3.1/tool_router/session。

Sessions 权限域还覆盖 MCP 服务器管理、MCP runtime 传输与 tool router MCP 传输（详见第七节完整路由表）。

七、场景三：工具执行需要 Tool execution 写权限

来自知识库原文：对于 Scoped Project API Key，composio.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 权限域覆盖以下写路由：

注意："查看工具定义"（Tools 域，只读）与"执行工具"（Tool execution 域，只写）是两个独立的权限域。即使你的 Key 能成功枚举工具（GET /api/v3.1/tools），也可能因为缺少 Tool execution 权限而无法真正执行。

7.2 修复步骤

1. 在 Dashboard 中核对发起调用的 Key 是否勾选了Tool execution = Write only（或 Read and write）；
2. 若未勾选，新建正确作用域的 Key 或用全权限 Key 重试；
3. 若 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（认证配置）：

Connected accounts（连接账户）：

Tools（查看工具定义）：

Toolkits（查看与安装工具包）：

Triggers（触发器；realtime 路由由 SDK 的triggers.subscribe()与 CLI 调用）：

Webhooks：

Observability（可观测性，读取执行日志与项目用量）：

Sessions（会话与 MCP；覆盖 MCP 服务器管理、MCP runtime 传输与 tool router MCP 传输）：

十、排障清单与最佳实践

1. 权限先行：任何 401/权限错误，先确认调用 Key 是否为 Scoped Key、对应权限域与级别是否满足路由要求，再排查 provider 连接。三个最容易踩坑的权限域是Proxy execute（Write）、Sessions（Write/Read and write）、Tool execution（Write/Read and write）。
2. 权限不可变：Scoped Key 的权限在创建时固化，调整权限 = 新建 Key + 轮换。生产环境建议为不同职责（代理执行、会话管理、工具执行、只读监控）分别创建最小权限 Key。
3. 区分"读"与"执行"：能GET /api/v3.1/tools（Tools 读）不代表能POST /api/v3.1/tools/execute/{tool_slug}（Tool execution 写）；能列 toolkits 不代表能建会话（Sessions 写）。
4. 泛化 401 的应对：SDK 可能把作用域权限不足表现为401 Invalid API key，请基于 Key 的权限配置诊断，而非直接判定 Key 失效。
5. 保留 request ID：联系支持时，使用正确作用域 Key 重新发起请求，并提供该请求的 request ID。

延伸阅读

• 权限完整参考：docs/content/reference/authenticating-to-composio/project-api-key-permissions.mdx
• Proxy Execute 用法详解：docs/content/docs/extending-sessions/proxy-execute.mdx
• API v3.1 变更说明（工具端点默认 latest 版本）：docs/content/changelog/04-08-26-v31-api.mdx
• Python 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