Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: limit permission updates to session changes and reference labels
Mukund committed
Sep 15, 2026 at 15:54 UTC
65255d31ac607f63a264a820702cbee3151306ab
4 files changed
+68
-77
docs/content/changelog/08-28-26-api-key-session-permissions.mdx
+1
-3
@@ -1,6 +1,6 @@
1
---
2
title: "Granular session permissions for scoped API keys"
3
-description: "Scoped project API keys now separate session management from session tool execution, with dedicated access for older MCP APIs."
3
+description: "Scoped project API keys now separate session management from session tool execution."
4
date: "2026-08-28"
5
---
6
@@ -10,5 +10,3 @@ Scoped project API keys now give you separate controls for session management an
10
11
- **Session management** controls creating, viewing, configuring, and deleting sessions.
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.
docs/content/kb/guide/platform-project-api-key-permissions.mdx
+10
-13
@@ -9,30 +9,27 @@ freshness: "evergreen"
9
topics: ["authentication","errors-and-troubleshooting","sessions-and-execution"]
10
aliases: ["/kb/sdk-and-api/platform-project-api-key-permissions","org-api-created-keys-do-not-currently-enable-proxy-execute","tool-router-session-creation-requires-sessions-write-access"]
11
---
12
-## Proxy execute (Legacy) requires an explicitly allowed Project API key
12
+## Proxy Execute requires an explicitly allowed Project API key
13
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.
14
+Create a scoped Project API key in the Dashboard and enable **Proxy Execute**
15
+during key creation before calling the v3.1 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.
18
19
## Tool Router session creation requires Session management write access
20
18
-For newly created scoped Project API keys, creating a session through Python's `composio.sessions.create(...)` or `POST /api/v3.1/tool_router/session` requires the Session management permission with write or read/write access.
21
+For scoped Project API keys, creating a session through `composio.sessions.create(...)` or `POST /api/v3.1/tool_router/session` requires the Session management permission with write or read/write access.
22
23
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`.
24
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.
25
+Create a new Project API key with Session management set to Read and write, or use an appropriate full-access Project API key, then retry session creation.
26
24
-## Tool execution (Legacy) requires write access
27
+## Tool execution requires Tool execution write access
28
26
-For a newly created scoped Project API key, `composio.tools.execute()` and the direct tool execution API require Tool execution (Legacy) set to Write. A key without that permission can surface a generic 401 `Invalid API key` even when the key exists and is active.
29
+For a scoped Project API key, `composio.tools.execute()` and the tool-execute API require Tool execution set to Write or Read and write. A key without that permission can surface a generic 401 `Invalid API key` even when the key exists and is active.
30
28
-Create a correctly scoped Project API key or use an appropriate full-access Project API key, then retry.
31
+Create a correctly scoped Project API key or use an appropriate full-access Project API key, then retry. The current API may return a generic permission error, so diagnose this behavior from the key's permissions.
32
33
## Session tool execution requires write access
34
35
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
-
36
-Use MCP (Legacy) read or write access to view or manage MCP servers and instances. Connecting to an MCP transport requires MCP (Legacy) write access and grants every capability exposed by that server.
37
-
38
-See [Scoped Project API Key](/reference/authenticating-to-composio/project-api-key-permissions) for the complete permission and route reference.
docs/content/reference/authenticating-to-composio/project-api-key-permissions.mdx
+47
-48
@@ -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. New scoped keys use the permission areas and access levels on this page.
17
+Default project API keys keep full project API key access. Scoped keys use the permission areas and access levels on this page.
18
</Callout>
19
20
## Create a scoped API key
@@ -23,7 +23,7 @@ Create a scoped key from the dashboard:
23
24
<Steps>
25
<Step>
26
-Go to the [Composio Dashboard](https://dashboard.composio.dev?utm_source=docs&utm_medium=content&utm_campaign=project-api-key-permissions).
26
+Go to the [Composio Dashboard](https://dashboard.composio.dev).
27
</Step>
28
<Step>
29
Select **Platform**.
@@ -57,8 +57,6 @@ The REST tables show paths relative to the API base URL, with each operation lis
57
58
## Permission areas
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
-
60
Jump to each permission area to see the routes it covers.
61
62
| Permission area | Available levels | Routes |
@@ -66,15 +64,15 @@ Jump to each permission area to see the routes it covers.
64
| Auth configs | No access, Read only, Write only, Read and write | [View routes](#auth-configs) |
65
| Connected accounts | No access, Read only, Write only, Read and write | [View routes](#connected-accounts) |
66
| Tools | No access, Read only | [View routes](#tools) |
69
-| Tool execution (Legacy) | No access, Write only | [View routes](#tool-execution-legacy) |
67
| Session management | No access, Read only, Write only, Read and write | [View routes](#session-management) |
68
| Session tool execution | No access, Write only | [View routes](#session-tool-execution) |
72
-| MCP (Legacy) | No access, Read only, Write only, Read and write | [View routes](#mcp-legacy) |
73
-| Proxy execute (Legacy) | No access, Write only | [View routes](#proxy-execute-legacy) |
69
| Toolkits | No access, Read only, Write only, Read and write | [View routes](#toolkits) |
70
| Triggers | No access, Read only, Write only, Read and write | [View routes](#triggers) |
71
| Webhooks | No access, Read only, Write only, Read and write | [View routes](#webhooks) |
72
| Observability | No access, Read only | [View routes](#observability) |
73
+| MCP (Legacy) | No access, Read only, Write only, Read and write | [View routes](#mcp-legacy) |
74
+| Tool execution (Legacy) | No access, Write only | [View routes](#tool-execution-legacy) |
75
+| Proxy execute (Legacy) | No access, Write only | [View routes](#proxy-execute-legacy) |
76
77
## Auth configs
78
@@ -119,17 +117,6 @@ View tool definitions, inputs, scopes, and versions.
117
| Read | `GET` | `/tools/get_scopes_required` |
118
| Read | `POST` | `/tools/execute/{tool_slug}/input` |
119
122
-## Tool execution (Legacy)
123
-
124
-Execute tools through the legacy direct execution API.
125
-
126
-| Access | Method | Route |
127
-| ------ | ------ | ---------------------------- |
128
-| Write | `POST` | `/tools/execute/{tool_slug}` |
129
-| Write | `POST` | `/files/upload/request` |
130
-| Write | `POST` | `/files/upload/response` |
131
-| Write | `GET` | `/files/list` |
132
-
120
## Session management
121
122
Create, view, configure, and delete sessions. This permission does not allow tool execution.
@@ -167,36 +154,6 @@ Search and execute tools through sessions and session-linked MCP servers. This i
154
155
For [session-linked MCP access](/docs/sessions-via-mcp), use `session.mcp.url` and `session.mcp.headers` unchanged. `POST` requests require Session tool execution with Write only access. The transport does not support `GET` (SSE) or `DELETE`; granting additional permissions does not enable those methods.
156
170
-## MCP (Legacy)
171
-
172
-Create, manage, and connect to MCP servers. Transport access grants every capability exposed by the configured MCP server.
173
-
174
-| Access | Method | Route |
175
-| ------ | -------- | -------------------------------------------------- |
176
-| Read | `GET` | `/mcp/servers` |
177
-| Read | `GET` | `/mcp/{id}` |
178
-| Read | `GET` | `/mcp/app/{app_key}` |
179
-| Read | `GET` | `/mcp/servers/{server_id}/instances` |
180
-| Write | `POST` | `/mcp/servers` |
181
-| Write | `POST` | `/mcp/servers/generate` |
182
-| Write | `POST` | `/mcp/servers/custom` |
183
-| Write | `PATCH` | `/mcp/{id}` |
184
-| Write | `DELETE` | `/mcp/{id}` |
185
-| Write | `POST` | `/mcp/servers/{server_id}/instances` |
186
-| Write | `DELETE` | `/mcp/servers/{server_id}/instances/{instance_id}` |
187
-
188
-For MCP transport access, use the returned MCP server URL unchanged. `POST` and `DELETE` requests require MCP (Legacy) with Write only or Read and write access.
189
-
190
-## Proxy execute (Legacy)
191
-
192
-Execute raw proxy requests through the legacy direct API.
193
-
194
-Use **Session tool execution** for new session-based integrations. The legacy proxy permission covers the routes below.
195
-
196
-| Access | Method | Route |
197
-| ------ | ------ | ------------------------------------------------- |
198
-| Write | `POST` | `/tools/execute/proxy` |
199
-
157
## Toolkits
158
159
View and install toolkits.
@@ -261,6 +218,48 @@ View execution logs and project usage summaries.
218
| Read | `POST` | `/project/usage/{entity_type}` |
219
| Read | `POST` | `/project/usage/summary` |
220
221
+## MCP (Legacy)
222
+
223
+Create, manage, and connect to MCP servers. Transport access grants every capability exposed by the configured MCP server.
224
+
225
+| Access | Method | Route |
226
+| ------ | -------- | -------------------------------------------------- |
227
+| Read | `GET` | `/mcp/servers` |
228
+| Read | `GET` | `/mcp/{id}` |
229
+| Read | `GET` | `/mcp/app/{app_key}` |
230
+| Read | `GET` | `/mcp/servers/{server_id}/instances` |
231
+| Write | `POST` | `/mcp/servers` |
232
+| Write | `POST` | `/mcp/servers/generate` |
233
+| Write | `POST` | `/mcp/servers/custom` |
234
+| Write | `PATCH` | `/mcp/{id}` |
235
+| Write | `DELETE` | `/mcp/{id}` |
236
+| Write | `POST` | `/mcp/servers/{server_id}/instances` |
237
+| Write | `DELETE` | `/mcp/servers/{server_id}/instances/{instance_id}` |
238
+
239
+For MCP transport access, use the returned MCP server URL unchanged. `POST` and `DELETE` requests require MCP (Legacy) with Write only or Read and write access.
240
+
241
+## Tool execution (Legacy)
242
+
243
+Execute predefined Composio tools.
244
+
245
+| Access | Method | Route |
246
+| ------ | ------ | ---------------------------- |
247
+| Write | `POST` | `/tools/execute/{tool_slug}` |
248
+| Write | `POST` | `/files/upload/request` |
249
+| Write | `POST` | `/files/upload/response` |
250
+| Write | `GET` | `/files/list` |
251
+
252
+## Proxy execute (Legacy)
253
+
254
+Execute raw proxy requests against connected accounts.
255
+
256
+Proxy execute is separate from tool execution. Grant it only when your application needs to call a connected account API through the raw proxy path.
257
+
258
+| Access | Method | Route |
259
+| ------ | ------ | ------------------------------------------------- |
260
+| Write | `POST` | `/tools/execute/proxy` |
261
+| Write | `POST` | `/tool_router/session/{session_id}/proxy_execute` |
262
+
263
## What to read next
264
265
<Cards>
docs/kb/articles/platform-project-api-key-permissions.md
+10
-13
@@ -1,27 +1,24 @@
1
-## Proxy execute (Legacy) requires an explicitly allowed Project API key
1
+## Proxy Execute requires an explicitly allowed Project API key
2
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.
3
+Create a scoped Project API key in the Dashboard and enable **Proxy Execute**
4
+during key creation before calling the v3.1 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.
7
8
## Tool Router session creation requires Session management write access
9
7
-For newly created scoped Project API keys, creating a session through Python's `composio.sessions.create(...)` or `POST /api/v3.1/tool_router/session` requires the Session management permission with write or read/write access.
10
+For scoped Project API keys, creating a session through `composio.sessions.create(...)` or `POST /api/v3.1/tool_router/session` requires the Session management permission with write or read/write access.
11
12
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`.
13
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.
14
+Create a new Project API key with Session management set to Read and write, or use an appropriate full-access Project API key, then retry session creation.
15
13
-## Tool execution (Legacy) requires write access
16
+## Tool execution requires Tool execution write access
17
15
-For a newly created scoped Project API key, `composio.tools.execute()` and the direct tool execution API require Tool execution (Legacy) set to Write. A key without that permission can surface a generic 401 `Invalid API key` even when the key exists and is active.
18
+For a scoped Project API key, `composio.tools.execute()` and the tool-execute API require Tool execution set to Write or Read and write. A key without that permission can surface a generic 401 `Invalid API key` even when the key exists and is active.
19
17
-Create a correctly scoped Project API key or use an appropriate full-access Project API key, then retry.
20
+Create a correctly scoped Project API key or use an appropriate full-access Project API key, then retry. The current API may return a generic permission error, so diagnose this behavior from the key's permissions.
21
22
## Session tool execution requires write access
23
24
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
-
25
-Use MCP (Legacy) read or write access to view or manage MCP servers and instances. Connecting to an MCP transport requires MCP (Legacy) write access and grants every capability exposed by that server.
26
-
27
-See [Scoped Project API Key](/reference/authenticating-to-composio/project-api-key-permissions) for the complete permission and route reference.