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, 12:15 UTC
docs: focus scoped key guidance on session permissions
Mukund committed
Sep 15, 2026 at 13:53 UTC
b7ac0ec68d71decfdf779e18317f8635d9aea9df
4 files changed
+10
-33
docs/content/changelog/08-28-26-api-key-session-permissions.mdx
-2
@@ -12,5 +12,3 @@ Scoped project API keys now give you separate controls for session management an
12
- **Session tool execution** covers search, tool execution, proxy execution, and session-linked MCP access.
13
- **MCP (Legacy)** controls older non-session MCP APIs, including server management and transport access.
14
- **Tool execution (Legacy)** and **Proxy execute (Legacy)** are the updated labels for the existing direct execution permissions.
15
-
16
-Existing keys with the legacy **Sessions** permission keep the same access. New keys use the granular permissions instead.
docs/content/kb/guide/platform-project-api-key-permissions.mdx
+3
-8
@@ -11,10 +11,7 @@ aliases: ["/kb/sdk-and-api/platform-project-api-key-permissions","org-api-create
11
---
12
## Proxy execute (Legacy) requires an explicitly allowed Project API key
13
14
-Create a scoped Project API key in the Dashboard and enable **Proxy execute (Legacy)**
15
-during key creation before calling the direct Proxy Execute API. If a request is
16
-denied, verify the key's scope before debugging the provider connection. Use a
17
-fresh request ID from the correctly scoped key when contacting Composio support is still necessary.
14
+Use **Session tool execution** for new session-based integrations. The older direct Proxy Execute API requires **Proxy execute (Legacy)**. If an existing integration is denied access to that API, check the key's permissions before debugging the provider connection.
15
16
## Tool Router session creation requires Session management write access
17
@@ -22,7 +19,7 @@ For newly created scoped Project API keys, creating a session through Python's `
19
20
A key can successfully call `GET /api/v3.1/toolkits` with Toolkits read access and still be unable to create a session. The SDK can surface a scoped-permission denial as a generic 401 `Invalid API key`.
21
25
-Create a new Project API key with Session management set to Write only, then retry session creation. Choose Read and write if you also need to retrieve sessions. Existing keys with the legacy Sessions permission continue to work without changes.
22
+Create a new Project API key with Session management set to Write only, then retry session creation. Choose Read and write if you also need to retrieve sessions.
23
24
## Tool execution (Legacy) requires write access
25
@@ -32,9 +29,7 @@ Create a correctly scoped Project API key or use an appropriate full-access Proj
29
30
## Session tool execution requires write access
31
35
-Session search, tool execution, proxy execution, and session-linked MCP access require Session tool execution set to Write. Session proxy execution also accepts Proxy execute (Legacy), so existing Proxy execute keys keep working. A key with Session tool execution can invoke any tool exposed by the session-linked MCP server.
36
-
37
-Existing keys with the legacy Sessions permission retain the session execution and MCP access they had before the permission split. They do not gain session proxy execution.
32
+Set **Session tool execution** to Write to search and execute tools through a session or its MCP server. This permission also covers session proxy requests and allows the key to invoke any tool exposed by the session-linked MCP server.
33
34
## Legacy MCP routes require MCP (Legacy) access
35
docs/content/reference/authenticating-to-composio/project-api-key-permissions.mdx
+4
-15
@@ -14,7 +14,7 @@ You pick a key's permissions when you create it, and they can't be changed after
14
</Callout>
15
16
<Callout type="info">
17
-Default project API keys keep full project API key access. Scoped keys use the permission areas and access levels on this page.
17
+Default project API keys keep full project API key access. New scoped keys use the permission areas and access levels on this page.
18
</Callout>
19
20
## Create a scoped API key
@@ -59,7 +59,7 @@ The REST tables show paths relative to the API base URL, with each operation lis
59
60
For a session-based integration, grant **Session management** to create and configure sessions, and **Session tool execution** to search and execute tools. Write only is enough to create sessions. Choose Read and write if you also need to retrieve them.
61
62
-Jump to each permission area to see the routes it covers. The dashboard labels **Tool execution (Legacy)** and **Proxy execute (Legacy)** still use the permission identifiers `tool_execution` and `proxy_execute`.
62
+Jump to each permission area to see the routes it covers.
63
64
| Permission area | Available levels | Routes |
65
| ----------------------- | ------------------------------------------------ | -------------------------------------- |
@@ -75,7 +75,6 @@ Jump to each permission area to see the routes it covers. The dashboard labels *
75
| Triggers | No access, Read only, Write only, Read and write | [View routes](#triggers) |
76
| Webhooks | No access, Read only, Write only, Read and write | [View routes](#webhooks) |
77
| Observability | No access, Read only | [View routes](#observability) |
78
-| Sessions (legacy) | Existing keys only | [View routes](#sessions-legacy) |
78
79
## Auth configs
80
@@ -135,7 +134,7 @@ Execute tools through the legacy direct execution API.
134
135
Create, view, configure, and delete sessions. This permission does not allow tool execution.
136
138
-The Session config read routes below are experimental and require Session configs to be enabled for your project. Existing `sessions` grants do not cover these routes.
137
+The Session config read routes below are experimental and require Session configs to be enabled for your project.
138
139
| Access | Method | Route |
140
| ------ | -------- | ------------------------------------------------------------------ |
@@ -192,7 +191,7 @@ For MCP transport access, use the returned MCP server URL unchanged. `POST` and
191
192
Execute raw proxy requests against connected accounts through direct and session proxy routes.
193
195
-Proxy execute is separate from tool execution. Session proxy routes accept either Session tool execution or Proxy execute (Legacy). Use Session tool execution for new session-based integrations; existing Proxy execute keys retain their access.
194
+Use **Session tool execution** for new session-based integrations. The legacy proxy permission covers the routes below.
195
196
| Access | Method | Route |
197
| ------ | ------ | ------------------------------------------------- |
@@ -263,16 +262,6 @@ View execution logs and project usage summaries.
262
| Read | `POST` | `/project/usage/{entity_type}` |
263
| Read | `POST` | `/project/usage/summary` |
264
266
-## Sessions (legacy)
267
-
268
-The `sessions` permission is no longer available when you create a scoped API key. Existing keys keep their original permission grants. New routes, such as Session config reads, are not added to these grants.
269
-
270
-- Existing `sessions: read` grants continue to cover session reads and legacy MCP server reads.
271
-- Existing `sessions: write` grants continue to cover session management writes, legacy MCP server writes, session `execute`, `execute_meta`, and `search` routes, and MCP transport writes. They do not cover session proxy execution.
272
-- Existing `sessions: read_write` grants continue to cover both sets of routes.
273
-
274
-For new session-based integrations, combine `session_management` and `session_tool_execution`. Add `legacy_mcp`, `tool_execution`, or `proxy_execute` only if your application still calls the older MCP, direct tool execution, or direct proxy APIs.
275
-
265
## What to read next
266
267
<Cards>
docs/kb/articles/platform-project-api-key-permissions.md
+3
-8
@@ -1,9 +1,6 @@
1
## Proxy execute (Legacy) requires an explicitly allowed Project API key
2
3
-Create a scoped Project API key in the Dashboard and enable **Proxy execute (Legacy)**
4
-during key creation before calling the direct Proxy Execute API. If a request is
5
-denied, verify the key's scope before debugging the provider connection. Use a
6
-fresh request ID from the correctly scoped key when contacting Composio support is still necessary.
3
+Use **Session tool execution** for new session-based integrations. The older direct Proxy Execute API requires **Proxy execute (Legacy)**. If an existing integration is denied access to that API, check the key's permissions before debugging the provider connection.
4
5
## Tool Router session creation requires Session management write access
6
@@ -11,7 +8,7 @@ For newly created scoped Project API keys, creating a session through Python's `
8
9
A key can successfully call `GET /api/v3.1/toolkits` with Toolkits read access and still be unable to create a session. The SDK can surface a scoped-permission denial as a generic 401 `Invalid API key`.
10
14
-Create a new Project API key with Session management set to Write only, then retry session creation. Choose Read and write if you also need to retrieve sessions. Existing keys with the legacy Sessions permission continue to work without changes.
11
+Create a new Project API key with Session management set to Write only, then retry session creation. Choose Read and write if you also need to retrieve sessions.
12
13
## Tool execution (Legacy) requires write access
14
@@ -21,9 +18,7 @@ Create a correctly scoped Project API key or use an appropriate full-access Proj
18
19
## Session tool execution requires write access
20
24
-Session search, tool execution, proxy execution, and session-linked MCP access require Session tool execution set to Write. Session proxy execution also accepts Proxy execute (Legacy), so existing Proxy execute keys keep working. A key with Session tool execution can invoke any tool exposed by the session-linked MCP server.
25
-
26
-Existing keys with the legacy Sessions permission retain the session execution and MCP access they had before the permission split. They do not gain session proxy execution.
21
+Set **Session tool execution** to Write to search and execute tools through a session or its MCP server. This permission also covers session proxy requests and allows the key to invoke any tool exposed by the session-linked MCP server.
22
23
## Legacy MCP routes require MCP (Legacy) access
24