Per-action permissions

A connected account holds a user's credentials for an app. A session decides which actions an agent can take with those credentials. You set the session's policy with toolkit, tool, and hint filters, and the Composio backend checks it on every Composio tool call made through the session. A tool the policy blocks never reaches the app's API. Local tools run in your own process and need their own checks.

Permissions in Composio sit at four layers. Each one answers a different question:

LayerControlsWhere you set it
OAuth scopesWhat the app's API lets the credentials doAuth config
Connected account ownershipWhose credentials a call usesuser_id on the session or execution
Session tool policyWhich toolkits and tools the agent can runtoolkits, tools, and tags on the session
Approvals and FirewallWhether a person or a check signs off on a specific call (both experimental)require_approval and hooks on the session

Scopes are the only layer the app itself enforces. The other three run in Composio before the request goes out.

Allow one tool, deny the rest

This example uses Hacker News, which needs no connected account, so you can run it with only an API key. The session allows HACKERNEWS_GET_USER and nothing else from the toolkit.

from composio import Composio
from composio_client import BadRequestError

composio = Composio()

session = composio.create(
    user_id="user_123",
    toolkits=["hackernews"],
    tools={"hackernews": {"enable": ["HACKERNEWS_GET_USER"]}},
)

allowed = session.execute("HACKERNEWS_GET_USER", arguments={"username": "pg"})
print(allowed.result_type)  # completed

try:
    session.execute("HACKERNEWS_GET_LATEST_POSTS", arguments={})
except BadRequestError as error:
    print(error.message)
    # 400 [Session Restriction] Tool 'HACKERNEWS_GET_LATEST_POSTS' is not enabled for this session. ...

The same policy shape works with disable lists, toolkit allowlists, and hint filters such as tags: { disable: ["destructiveHint"] }. See Configuring sessions for every option. If you change the policy with session.update(), the next call follows the new policy.

Where the session policy applies

We checked each path below against a test project with an allowed and a blocked tool. For apps that need credentials, we used a connection with a deliberately invalid key: an allowed call came back with the app's own "invalid API key" error, so it reached the app, and a blocked call came back with a Composio error, so it never left Composio.

PathBlocked tool
session.execute() and POST /tool_router/session/{id}/executeRejected with a session restriction error
COMPOSIO_MULTI_EXECUTE_TOOLThat tool's result carries the session restriction error. Allowed tools in the same batch still run
run_composio_tool() inside the sandboxRejected with the same error. Sandbox credentials only work for their own session: calls to the direct execution endpoint or to another session's endpoints return 401
Session MCP URLNot listed in tools/list, so a direct tools/call returns Tool ... not found. Through COMPOSIO_MULTI_EXECUTE_TOOL, it returns the session restriction error
COMPOSIO_SEARCH_TOOLSLeft out of results. The response tells the agent the tool is restricted
session.proxyExecute() and COMPOSIO_PROXY_EXECUTERefused with 403 for any toolkit that has a tool allowlist, denylist, or applicable hint filter, so the proxy can't be used to reach an endpoint whose tool you blocked
Tools that need approvalReturn input_required and don't run until the person answers. Two exceptions: over MCP, a client without elicitation support runs them without asking if you set no_elicitation_support_fallback to "allow", and a sandbox script can call a tool the approval check misses. If approval must never be skipped, disable the sandbox. See Approvals

Ownership is checked on both session and direct execution. A session can't be pinned to another user's connected account (4306), and a direct execution with a connected_account_id that belongs to a different user_id fails (1812). Which Composio user_id a request maps to is still your application's decision. See Building B2B agents for shared and workspace-owned connections.

What the session policy does not cover

These limits are current behavior. Plan around them.

  • Direct execution has no session policy. composio.tools.execute() and POST /api/v3/tools/execute/{tool_slug} run any tool in the project for the user's connected account. Your backend decides which tools to call on this path. Give agents a session instead of direct execution when you want Composio to enforce a tool policy.
  • Proxy calls on an unfiltered toolkit can reach any endpoint on its domain. In a session, a toolkit with no tool or hint filters allows proxy calls to any endpoint on that toolkit's API domain. The legacy POST /api/v3/tools/execute/proxy takes a connected account ID and never checks a session policy. Use OAuth scopes to bound what the credentials can do at the app.
  • Auth config tool lists don't block execution. The deprecated tool_access_config.tools_available_for_execution and restrict_to_following_tools fields are saved and returned, but tools outside them still run on direct and session execution. Set scopes on the auth config and tool filters on the session instead.
  • Local tools run in your process. SDK local tools and toolkits run in your application when session.execute() calls them, without a backend policy check. Put permission checks in their handlers.
  • Scoped API keys gate endpoints, not tools. Project API key permissions decide whether a key can manage sessions, execute tools, or use the proxy. They don't pick individual tools.

Error codes

CodeSlugCause
4310ToolRouterV2_ToolNotInEnabledListThe tool isn't in the toolkit's enable list
4311ToolRouterV2_ToolDisabledInSessionThe tool is in the toolkit's disable list
4324ToolRouterV2_ToolkitNotAllowedThe toolkit isn't in the session's toolkit allowlist
4325ToolRouterV2_ToolkitDisabledThe toolkit is in the session's toolkit denylist
4328ToolRouterV2_ToolTagNotAllowedA hint filter blocks the tool
4327ToolRouterV2_ProxyExecutionDisabledProxy call to a toolkit that has tool or hint filters
4306ToolRouterV2_InvalidConnectedAccountIdsThe session names a connected account that belongs to another user
1812ActionExecute_ConnectedAccountEntityIdMismatchDirect execution with a connected account that belongs to another user

In TypeScript, read the code from error.apiErrorCode on ComposioToolExecutionError. In Python, session.execute() raises composio_client.BadRequestError with status_code 400.