Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 03:37 UTC
docs: per-action permissions page with verified allow/deny behavior (DEVREL-316) (#5457)
## Problem Agent-preference runs (Gauge) keep recommending Arcade over Composio because agents conclude "Composio enforces permissions per connection, not per action." It was the most frequent Composio objection in the 2026-11-09 head-to-head runs (8 of 20 sessions, then 5 of 8 Arcade-vs-Composio sessions). Sessions do enforce per-tool policy, but no doc page says so, says where the policy is checked, or shows it rejecting a call. [DEVREL-316](https://linear.app/composio/issue/DEVREL-316) ## What changed - New page **Governance → Per-action permissions** (`docs/content/docs/governance/action-permissions.mdx`): - the four permission layers (OAuth scopes, connection ownership, session tool policy, approvals/Firewall) - a runnable allow/deny example in Python, TypeScript, and cURL using Hacker News, which needs no connected account - a table of execution paths and what each does with a blocked tool - what the session policy does **not** cover: direct execution, proxy on unfiltered toolkits and the legacy proxy endpoint, deprecated auth-config tool lists, scoped API keys - error codes - One-line links to it from Configuring sessions (tool filters) and Controlling scopes. - Sidebar and home navigation entries, with the nav tests updated to match. ## Evidence All results come from live calls against an internal test project (`testnoauth`, with no customer data), run on 2026-11-18. For apps that need credentials I used an OpenAI connection with a deliberately invalid key. An allowed call came back with OpenAI's own `invalid_api_key` error, which proves it reached OpenAI. A blocked call came back with a Composio error, which proves it never left Composio. | Path | Blocked tool | Result | |---|---|---| | `POST /tool_router/session/{id}/execute` | not in `enable` list | `400` `4310 ToolRouterV2_ToolNotInEnabledList` | | same | in `disable` list (set via `PATCH` on a live session) | `400` `4311`, effective on the next call | | same | toolkit not in allowlist / in denylist | `4324` / `4325` | | same | `tags.disable: ["destructiveHint"]` | `4328 ToolRouterV2_ToolTagNotAllowed` | | `COMPOSIO_MULTI_EXECUTE_TOOL` | not in `enable` list | per-tool `[Session Restriction]` error, allowed tool in the same batch ran | | sandbox `run_composio_tool()` | not in `enable` list | `4310`. From inside the sandbox, `/api/v3/tools/execute` → `401` "Workbench credentials are not accepted on this endpoint". Another session's execute → `401` | | session MCP URL | not in `enable` list | absent from `tools/list`, `tools/call` → "not found", via multi-execute → `[Session Restriction]` | | `COMPOSIO_SEARCH_TOOLS` | not in `enable` list | left out of results, named as restricted in guidance | | session `proxy_execute` / `COMPOSIO_PROXY_EXECUTE` | toolkit has a tool list or tag filter | `403` `4327 ToolRouterV2_ProxyExecutionDisabled` | | session create, bob pinned to alice's `ca_` | n/a | `400` `4306` | | `/api/v3/tools/execute`, `user_id` bob + alice's `ca_` | n/a | `400` `1812` | | **`/api/v3/tools/execute` (direct)** | tool blocked in sessions | **reached OpenAI** (no session, so no session policy) | | **auth config `tools_available_for_execution` + `restrict_to_following_tools`** | tool outside the list | **reached OpenAI** on both direct and session execution, retried after 90 s | | **legacy `/api/v3/tools/execute/proxy`** | n/a | **forwarded** with only `connected_account_id`. Direct execute requires `user_id` (`1811`) | The page's SDK examples were run as written, swapping only the constructor for user-key auth scoped to the test project: ``` $ python allow_deny.py # composio from this repo completed 400 4310 400 [Session Restriction] Tool 'HACKERNEWS_GET_LATEST_POSTS' is not enabled for this session. You cannot execute this tool. $ bun run.ts # @composio/core@0.30.0, the docs pin completed 400 4310 Error executing the tool HACKERNEWS_GET_LATEST_POSTS: [Session Restriction] Tool 'HACKERNEWS_GET_LATEST_POSTS' is not enabled for this session. You cannot execute this tool. ``` Local checks from `docs/`: `bun run test` (838 pass, 0 fail), `check:code-examples`, `check:python-snippets`, `check:typescript-snippets`, `scripts/validate-links.ts`, all clean. Production build: see the comment below. ## Details and open questions Not tested: legacy single-toolkit MCP servers (`allowed_tools`). Their endpoint takes only a project API key, and I couldn't mint one for the test project through a public route, so the page makes no claim about them. Questions for product/security, not decided here: 1. **Auth config tool lists.** The API accepts `tool_access_config.tools_available_for_execution` and `restrict_to_following_tools`, stores them, and returns them, but they don't block execution. Is that a bug, or intended because the fields are deprecated? If intended, should the API reject or warn on them instead of silently accepting them? 2. **Direct execution and the legacy proxy** don't apply any tool policy, and the legacy proxy doesn't require `user_id`. Is that the intended contract, given that the project key holder is trusted? The page states it as current behavior. 3. **What to promise publicly.** The page describes observed behavior ("we checked each path"). Is product comfortable with that framing and with publishing the limitations section? 4. Blocked tools on the session MCP URL return "not found" rather than a restriction error. That's minor, but agents may read it as a missing tool. ## ELI5 When you give an AI agent access to someone's Gmail, you can also tell Composio "this agent may only read email, not send it." This page shows that rule being enforced: the "send" call gets refused before it reaches Gmail. It also lists the few places where the rule doesn't apply, so nobody assumes more than is true. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>