@devries-cameron20 / composio-1 / commits / 25170ec29
Fork 0

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: document granular session and MCP permissions

Mukund committed Aug 25, 2026 at 19:49 UTC 25170ec29e146c14037a4d4c5673639c63cd6b6a
5 files changed +172 -79
docs/content/changelog/08-28-26-api-key-session-permissions.mdx new
+16
@@ -0,0 +1,16 @@
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."
4 +date: "2026-08-28"
5 +---
6 +
7 +Scoped project API keys now give you separate controls for session management and session-based execution.
8 +
9 +### What's new
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.
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
+20 -10
@@ -4,29 +4,39 @@ description: "Public guidance for scoped Project API key permissions."
4 keywords: ["api-keys","permissions","platform","sessions","tool-router","authentication","errors-and-troubleshooting","sessions-and-execution","/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"]
5 sources: [{"sourcePath":"platform/project-api-key-permissions/public.md","sourceHeading":"Proxy Execute requires an explicitly allowed Project API key"},{"sourcePath":"platform/project-api-key-permissions/public.md","sourceHeading":"Tool Router session creation requires Sessions write access"},{"sourcePath":"platform/project-api-key-permissions/public.md","sourceHeading":"Tool execution requires Tool execution write access"}]
6 sourceCommit: "5eac683455ff252a7a3b62f33ab6566445009b52"
7 -lastVerifiedAt: "2026-08-17"
8 -reviewAfter: "2026-11-15"
7 +lastVerifiedAt: "2026-08-28"
8 +reviewAfter: "2026-11-26"
9 freshness: "evergreen"
10 topics: ["authentication","errors-and-troubleshooting","sessions-and-execution"]
11 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"]
12 ---
13 -## Proxy Execute requires an explicitly allowed Project API key
13 +## Proxy execute (Legacy) requires an explicitly allowed Project API key
14
15 -Create a scoped Project API key in the Dashboard and enable **Proxy Execute**
15 +Create a scoped Project API key in the Dashboard and enable **Proxy execute (Legacy)**
16 during key creation before calling the v3.1 Proxy Execute API. If a request is
17 denied, verify the key's scope before debugging the provider connection. Use a
18 fresh request ID from the correctly scoped key when contacting Composio support is still necessary.
19
20 -## Tool Router session creation requires Sessions write access
20 +## Tool Router session creation requires Session management write access
21
22 -For scoped Project API keys, creating a session through `composio.sessions.create(...)` or `POST /api/v3.1/tool_router/session` requires the Sessions permission with write or read/write access.
22 +For newly created 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.
23
24 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`.
25
26 -Create a new Project API key with Sessions set to Read and write, or use an appropriate full-access Project API key, then retry session creation.
26 +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. Existing keys with the legacy Sessions permission continue to work without changes.
27
28 -## Tool execution requires Tool execution write access
28 +## Tool execution (Legacy) requires write access
29
30 -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 +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.
31
32 -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 +Create a correctly scoped Project API key or use an appropriate full-access Project API key, then retry.
33 +
34 +## Session tool execution requires write access
35 +
36 +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.
37 +
38 +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.
39 +
40 +## Legacy MCP routes require MCP (Legacy) access
41 +
42 +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.
docs/content/reference/authenticating-to-composio/project-api-key-permissions.mdx
+115 -58
@@ -53,24 +53,27 @@ Click **Create API Key**, then choose the permission areas and access levels bel
53
54 Some read routes use `POST` because the request body carries filters or lookup input. The access level is based on what the route does, not only the HTTP method.
55
56 -When v3 and v3.1 expose the same route shape, this page lists one representative version instead of repeating both. Version-specific routes are listed separately.
56 +The session, MCP, and proxy tables list both v3 and v3.1 routes explicitly. Elsewhere, equivalent routes may be represented by one version. Version-specific routes are listed separately, and MCP transport routes use their public paths.
57
58 ## Permission areas
59
60 Jump to each permission area to see the routes it covers.
61
62 -| Permission area | Available levels | Routes |
63 -| ------------------ | ------------------------------------------------ | ---------------------------------- |
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) |
67 -| Tool execution | No access, Write only | [View routes](#tool-execution) |
68 -| Proxy execute | No access, Write only | [View routes](#proxy-execute) |
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 -| Sessions | No access, Read only, Write only, Read and write | [View routes](#sessions) |
62 +| Permission area | Available levels | Routes |
63 +| ------------------------ | ------------------------------------------------ | --------------------------------------- |
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) |
67 +| Tool execution (Legacy) | No access, Write only | [View routes](#tool-execution-legacy) |
68 +| Session management | No access, Read only, Write only, Read and write | [View routes](#session-management) |
69 +| Session tool execution | No access, Write only | [View routes](#session-tool-execution) |
70 +| MCP (Legacy) | No access, Read only, Write only, Read and write | [View routes](#mcp-legacy) |
71 +| Proxy execute (Legacy) | No access, Write only | [View routes](#proxy-execute-legacy) |
72 +| Toolkits | No access, Read only, Write only, Read and write | [View routes](#toolkits) |
73 +| Triggers | No access, Read only, Write only, Read and write | [View routes](#triggers) |
74 +| Webhooks | No access, Read only, Write only, Read and write | [View routes](#webhooks) |
75 +| Observability | No access, Read only | [View routes](#observability) |
76 +| Sessions (legacy) | Existing keys only | [View routes](#sessions-legacy) |
77
78 ## Auth configs
79
@@ -115,27 +118,109 @@ View tool definitions, inputs, scopes, and versions.
118 | Read | `GET` | `/api/v3.1/tools/get_scopes_required` |
119 | Read | `POST` | `/api/v3.1/tools/execute/{tool_slug}/input` |
120
118 -## Tool execution
121 +## Tool execution (Legacy)
122
120 -Execute predefined Composio tools.
123 +Execute tools through the legacy direct execution API.
124
125 | Access | Method | Endpoint |
126 | ------ | ------ | ------------------------------------- |
127 +| Write | `POST` | `/api/v3/tools/execute/{tool_slug}` |
128 | Write | `POST` | `/api/v3.1/tools/execute/{tool_slug}` |
129 | Write | `POST` | `/api/v3/files/upload/request` |
130 | Write | `POST` | `/api/v3/files/upload/response` |
131 | Write | `GET` | `/api/v3/files/list` |
132
129 -## Proxy execute
133 +## Session management
134
131 -Execute raw proxy requests against connected accounts.
135 +Create, view, configure, and delete sessions. This permission does not allow tool execution.
136
133 -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.
134 -
135 -| Access | Method | Endpoint |
136 -| ------ | ------ | -------------------------------------------------------- |
137 -| Write | `POST` | `/api/v3.1/tools/execute/proxy` |
138 -| Write | `POST` | `/api/v3/tool_router/session/{session_id}/proxy_execute` |
137 +| Access | Method | Endpoint |
138 +| ------ | -------- | ------------------------------------------------------------------------- |
139 +| Read | `GET` | `/api/v3/tool_router/session/{session_id}` |
140 +| Read | `GET` | `/api/v3/tool_router/session/{session_id}/toolkits` |
141 +| Read | `GET` | `/api/v3/tool_router/session/{session_id}/tools` |
142 +| Read | `GET` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/items` |
143 +| Read | `GET` | `/api/v3.1/tool_router/session/{session_id}` |
144 +| Read | `GET` | `/api/v3.1/tool_router/session/{session_id}/toolkits` |
145 +| Read | `GET` | `/api/v3.1/tool_router/session/{session_id}/config_history` |
146 +| Read | `GET` | `/api/v3.1/tool_router/session/{session_id}/tools` |
147 +| Read | `GET` | `/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/items` |
148 +| Write | `POST` | `/api/v3/tool_router/session` |
149 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/link` |
150 +| Write | `PATCH` | `/api/v3/tool_router/session/{session_id}` |
151 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/upload_url` |
152 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/download_url` |
153 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/delete` |
154 +| Write | `POST` | `/api/v3.1/tool_router/session` |
155 +| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/attach` |
156 +| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/link` |
157 +| Write | `PATCH` | `/api/v3.1/tool_router/session/{session_id}` |
158 +| Write | `DELETE` | `/api/v3.1/tool_router/session/{session_id}` |
159 +| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/upload_url` |
160 +| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/download_url` |
161 +| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/mounts/{mount_id}/delete` |
162 +
163 +## Session tool execution
164 +
165 +Search and execute tools through sessions and session-linked MCP servers. This includes session proxy execution, so it grants every execution capability exposed through a session.
166 +
167 +| Access | Method | Endpoint |
168 +| ------ | ------ | -------------------------------------------------------------- |
169 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/execute` |
170 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/execute_meta` |
171 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/search` |
172 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/proxy_execute` |
173 +| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/execute` |
174 +| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/execute_meta` |
175 +| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/search` |
176 +| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/proxy_execute` |
177 +| Write | `POST` | `/tool_router/{session_id}/mcp` |
178 +
179 +## MCP (Legacy)
180 +
181 +Create, manage, and connect to MCP servers. Transport access grants every capability exposed by the configured MCP server.
182 +
183 +| Access | Method | Endpoint |
184 +| ------ | -------- | ------------------------------------------------------------------- |
185 +| Read | `GET` | `/api/v3/mcp/servers` |
186 +| Read | `GET` | `/api/v3.1/mcp/servers` |
187 +| Read | `GET` | `/api/v3/mcp/{id}` |
188 +| Read | `GET` | `/api/v3.1/mcp/{id}` |
189 +| Read | `GET` | `/api/v3/mcp/app/{app_key}` |
190 +| Read | `GET` | `/api/v3.1/mcp/app/{app_key}` |
191 +| Read | `GET` | `/api/v3/mcp/servers/{server_id}/instances` |
192 +| Read | `GET` | `/api/v3.1/mcp/servers/{server_id}/instances` |
193 +| Write | `POST` | `/api/v3/mcp/servers` |
194 +| Write | `POST` | `/api/v3.1/mcp/servers` |
195 +| Write | `POST` | `/api/v3/mcp/servers/generate` |
196 +| Write | `POST` | `/api/v3.1/mcp/servers/generate` |
197 +| Write | `POST` | `/api/v3/mcp/servers/custom` |
198 +| Write | `POST` | `/api/v3.1/mcp/servers/custom` |
199 +| Write | `PATCH` | `/api/v3/mcp/{id}` |
200 +| Write | `PATCH` | `/api/v3.1/mcp/{id}` |
201 +| Write | `DELETE` | `/api/v3/mcp/{id}` |
202 +| Write | `DELETE` | `/api/v3.1/mcp/{id}` |
203 +| Write | `POST` | `/api/v3/mcp/servers/{server_id}/instances` |
204 +| Write | `POST` | `/api/v3.1/mcp/servers/{server_id}/instances` |
205 +| Write | `DELETE` | `/api/v3/mcp/servers/{server_id}/instances/{instance_id}` |
206 +| Write | `DELETE` | `/api/v3.1/mcp/servers/{server_id}/instances/{instance_id}` |
207 +| Write | `POST` | `/v3/mcp/{server_id}/{transport}` |
208 +| Write | `POST` | `/v3.1/mcp/{server_id}/{transport}` |
209 +| Write | `DELETE` | `/v3/mcp/{server_id}/{transport}` |
210 +| Write | `DELETE` | `/v3.1/mcp/{server_id}/{transport}` |
211 +
212 +## Proxy execute (Legacy)
213 +
214 +Execute raw proxy requests against connected accounts through direct and session proxy routes.
215 +
216 +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.
217 +
218 +| Access | Method | Endpoint |
219 +| ------ | ------ | ----------------------------------------------------------------- |
220 +| Write | `POST` | `/api/v3/tools/execute/proxy` |
221 +| Write | `POST` | `/api/v3.1/tools/execute/proxy` |
222 +| Write | `POST` | `/api/v3/tool_router/session/{session_id}/proxy_execute` |
223 +| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/proxy_execute` |
224
225 ## Toolkits
226
@@ -199,43 +284,15 @@ View execution logs and project usage summaries.
284 | Read | `POST` | `/api/v3.1/project/usage/{entity_type}` |
285 | Read | `POST` | `/api/v3.1/project/usage/summary` |
286
202 -## Sessions
287 +## Sessions (legacy)
288
204 -Create and operate sessions and MCP servers. This permission area covers MCP server management, the MCP runtime transport, and the tool router MCP transport.
289 +The `sessions` permission is no longer available when you create a scoped API key. Existing keys keep their original access unchanged.
290
206 -| Access | Method | Endpoint |
207 -| ------ | -------- | ------------------------------------------------------------------------- |
208 -| Read | `GET` | `/api/v3/mcp/servers` |
209 -| Read | `GET` | `/api/v3/mcp/{id}` |
210 -| Read | `GET` | `/api/v3/mcp/app/{app_key}` |
211 -| Read | `GET` | `/api/v3/mcp/servers/{server_id}/instances` |
212 -| Read | `GET` | `/tool_router/{session_id}/mcp` |
213 -| Read | `GET` | `/api/v3.1/tool_router/session/{session_id}` |
214 -| Read | `GET` | `/api/v3/tool_router/session/{session_id}/toolkits` |
215 -| Read | `GET` | `/api/v3.1/tool_router/session/{session_id}/tools` |
216 -| Read | `GET` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/items` |
217 -| Read | `GET` | `/api/v3.1/tool_router/session/{session_id}/config_history` |
218 -| Write | `POST` | `/api/v3/mcp/servers` |
219 -| Write | `POST` | `/api/v3/mcp/servers/generate` |
220 -| Write | `POST` | `/api/v3/mcp/servers/custom` |
221 -| Write | `PATCH` | `/api/v3/mcp/{id}` |
222 -| Write | `DELETE` | `/api/v3/mcp/{id}` |
223 -| Write | `POST` | `/api/v3/mcp/servers/{server_id}/instances` |
224 -| Write | `DELETE` | `/api/v3/mcp/servers/{server_id}/instances/{instance_id}` |
225 -| Write | `POST` | `/api/v3/mcp/{server_id}/{transport}` |
226 -| Write | `DELETE` | `/api/v3/mcp/{server_id}/{transport}` |
227 -| Write | `POST` | `/tool_router/{session_id}/mcp` |
228 -| Write | `DELETE` | `/tool_router/{session_id}/mcp` |
229 -| Write | `POST` | `/api/v3.1/tool_router/session` |
230 -| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/execute` |
231 -| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/execute_meta` |
232 -| Write | `POST` | `/api/v3/tool_router/session/{session_id}/link` |
233 -| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/search` |
234 -| Write | `PATCH` | `/api/v3.1/tool_router/session/{session_id}` |
235 -| Write | `POST` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/upload_url` |
236 -| Write | `POST` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/download_url` |
237 -| Write | `POST` | `/api/v3/tool_router/session/{session_id}/mounts/{mount_id}/delete` |
238 -| Write | `POST` | `/api/v3.1/tool_router/session/{session_id}/attach` |
291 +- Existing `sessions: read` grants continue to cover session reads and legacy MCP server reads.
292 +- 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.
293 +- Existing `sessions: read_write` grants continue to cover both sets of routes.
294 +
295 +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.
296
297 ## What to read next
298
docs/kb/articles/platform-project-api-key-permissions.md
+18 -8
@@ -1,20 +1,30 @@
1 -## Proxy Execute requires an explicitly allowed Project API key
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**
3 +Create a scoped Project API key in the Dashboard and enable **Proxy execute (Legacy)**
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 Sessions write access
8 +## Tool Router session creation requires Session management write access
9
10 -For scoped Project API keys, creating a session through `composio.sessions.create(...)` or `POST /api/v3.1/tool_router/session` requires the Sessions permission with write or read/write access.
10 +For newly created 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
14 -Create a new Project API key with Sessions set to Read and write, or use an appropriate full-access Project API key, then retry session creation.
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. Existing keys with the legacy Sessions permission continue to work without changes.
15
16 -## Tool execution requires Tool execution write access
16 +## Tool execution (Legacy) requires write access
17
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.
18 +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.
19
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.
20 +Create a correctly scoped Project API key or use an appropriate full-access Project API key, then retry.
21 +
22 +## Session tool execution requires write access
23 +
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.
27 +
28 +## Legacy MCP routes require MCP (Legacy) access
29 +
30 +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.
docs/kb/manifest.json
+3 -3
@@ -1068,9 +1068,9 @@
1068 ],
1069 "relatedGuides": [],
1070 "externalResources": [],
1071 - "updatedAt": "2026-07-16",
1072 - "lastVerifiedAt": "2026-08-17",
1073 - "reviewAfter": "2026-11-15",
1071 + "updatedAt": "2026-08-28",
1072 + "lastVerifiedAt": "2026-08-28",
1073 + "reviewAfter": "2026-11-26",
1074 "freshness": "evergreen",
1075 "state": "published",
1076 "featured": false