@devries-cameron20 / composio Mirror · read-only
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 04:45 UTC

next
mdx 290 lines 14.7 KB
Raw
1 ---
2 title: Scoped Project API Key
3 description: Choose which project resources a scoped API key can access.
4 keywords: [project api keys, scoped api keys, permissions, access levels]
5 isNew: true
6 ---
7
8 <YouTube id="ySMu9lljkWg" title="Scoped Project API Key walkthrough" />
9
10 A scoped project API key lets you choose which project resources the key can access. Reach for one when a key needs only a subset of your project, such as executing tools, reading logs, or managing connected accounts.
11
12 <Callout type="warn">
13 You pick a key's permissions when you create it, and they can't be changed afterward. To adjust them, create a new key and rotate your application to use it.
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.
18 </Callout>
19
20 ## Create a scoped API key
21
22 Create a scoped key from the dashboard:
23
24 <Steps>
25 <Step>
26 Go to the [Composio Dashboard](https://dashboard.composio.dev).
27 </Step>
28 <Step>
29 Select **Platform**.
30 </Step>
31 <Step>
32 Select your project.
33 </Step>
34 <Step>
35 Go to **Settings**.
36 </Step>
37 <Step>
38 Open the **API Keys** tab.
39 </Step>
40 <Step>
41 Click **Create API Key**, then choose the permission areas and access levels below.
42 </Step>
43 </Steps>
44
45 ## Access levels
46
47 | Access level | What it allows |
48 | -------------- | ------------------------------------------------------------------- |
49 | No access | The key cannot use routes in that permission area. |
50 | Read only | The key can use read routes in that permission area. |
51 | Write only | The key can use write routes in that permission area. |
52 | Read and write | The key can use both read and write routes in that permission area. |
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 The REST tables show paths relative to the API base URL, with each operation listed once. Use the [API reference](/reference) for the full request URL and endpoint availability. MCP transports use the URL returned when you create a session or MCP server.
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 | 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) |
69 | Toolkits | No access, Read only | [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
79 View and modify auth configs.
80
81 | Access | Method | Route |
82 | ------ | -------- | --------------------------------- |
83 | Read | `GET` | `/auth_configs` |
84 | Read | `GET` | `/auth_configs/{nanoid}` |
85 | Write | `POST` | `/auth_configs` |
86 | Write | `PATCH` | `/auth_configs/{nanoid}` |
87 | Write | `DELETE` | `/auth_configs/{nanoid}` |
88 | Write | `PATCH` | `/auth_configs/{nanoid}/{status}` |
89
90 ## Connected accounts
91
92 View and manage connected accounts.
93
94 | Access | Method | Route |
95 | ------ | -------- | -------------------------------------- |
96 | Read | `GET` | `/connected_accounts` |
97 | Read | `GET` | `/connected_accounts/{nanoid}` |
98 | Write | `POST` | `/connected_accounts` |
99 | Write | `POST` | `/connected_accounts/link` |
100 | Write | `PATCH` | `/connected_accounts/{nanoid}` |
101 | Write | `PATCH` | `/connected_accounts/{nanoid}/status` |
102 | Write | `POST` | `/connected_accounts/{nanoid}/refresh` |
103 | Write | `DELETE` | `/connected_accounts/{nanoid}` |
104 | Write | `POST` | `/connected_accounts/{nanoid}/revoke` |
105
106 ## Tools
107
108 View tool definitions, inputs, scopes, and versions.
109
110 | Access | Method | Route |
111 | ------ | ------ | --------------------------------------- |
112 | Read | `GET` | `/tools` |
113 | Read | `GET` | `/tools/enum` |
114 | Read | `GET` | `/tools/{tool_slug}` |
115 | Read | `GET` | `/tools/{tool_slug}/get_latest_version` |
116 | Read | `GET` | `/tools/scopes/required` |
117 | Read | `GET` | `/tools/get_scopes_required` |
118 | Read | `POST` | `/tools/execute/{tool_slug}/input` |
119
120 ## Session management
121
122 Create, view, configure, and delete sessions. This permission does not allow tool execution.
123
124 The Session config read routes below are experimental and require Session configs to be enabled for your project.
125
126 | Access | Method | Route |
127 | ------ | -------- | ------------------------------------------------------------------ |
128 | Read | `GET` | `/session_configs` |
129 | Read | `GET` | `/session_configs/{session_config_id}` |
130 | Read | `GET` | `/tool_router/session/{session_id}` |
131 | Read | `GET` | `/tool_router/session/{session_id}/toolkits` |
132 | Read | `GET` | `/tool_router/session/{session_id}/tools` |
133 | Read | `GET` | `/tool_router/session/{session_id}/mounts/{mount_id}/items` |
134 | Read | `GET` | `/tool_router/session/{session_id}/config_history` |
135 | Write | `POST` | `/tool_router/session` |
136 | Write | `POST` | `/tool_router/session/{session_id}/link` |
137 | Write | `PATCH` | `/tool_router/session/{session_id}` |
138 | Write | `POST` | `/tool_router/session/{session_id}/mounts/{mount_id}/upload_url` |
139 | Write | `POST` | `/tool_router/session/{session_id}/mounts/{mount_id}/download_url` |
140 | Write | `POST` | `/tool_router/session/{session_id}/mounts/{mount_id}/delete` |
141 | Write | `POST` | `/tool_router/session/{session_id}/attach` |
142 | Write | `DELETE` | `/tool_router/session/{session_id}` |
143
144 ## Session tool execution
145
146 Search and execute tools through sessions and session-linked MCP servers, including session proxy requests. The session proxy route also accepts [Proxy execute](#proxy-execute-legacy) with Write only access. Either permission grants that route.
147
148 | Access | Method | Route |
149 | ------ | ------ | ------------------------------------------------ |
150 | Write | `POST` | `/tool_router/session/{session_id}/execute` |
151 | Write | `POST` | `/tool_router/session/{session_id}/execute_meta` |
152 | Write | `POST` | `/tool_router/session/{session_id}/search` |
153 | Write | `POST` | `/tool_router/session/{session_id}/proxy_execute` |
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
157 ## Toolkits
158
159 View toolkits.
160
161 | Access | Method | Route |
162 | ------ | ------ | ----------------------------------------------- |
163 | Read | `GET` | `/toolkits` |
164 | Read | `GET` | `/toolkits/{slug}` |
165 | Read | `GET` | `/toolkits/categories` |
166 | Read | `GET` | `/toolkits/changelog` |
167 | Read | `POST` | `/toolkits/{toolkit_slug}/scopes/recommended` |
168 | Read | `GET` | `/toolkits/{toolkit_slug}/scopes/grant_context` |
169 | Read | `POST` | `/toolkits/multi` |
170
171 ## Triggers
172
173 View trigger types, manage trigger instances, and subscribe to trigger events. The realtime routes are called by the SDK (`triggers.subscribe()`) and the CLI to receive trigger events.
174
175 | Access | Method | Route |
176 | ------ | -------- | --------------------------------------- |
177 | Read | `GET` | `/triggers_types` |
178 | Read | `GET` | `/triggers_types/{slug}` |
179 | Read | `GET` | `/triggers_types/list/enum` |
180 | Read | `GET` | `/trigger_instances/active` |
181 | Read | `GET` | `/cli/realtime/credentials` |
182 | Read | `POST` | `/cli/realtime/auth` |
183 | Read | `GET` | `/internal/sdk/realtime/credentials` |
184 | Read | `POST` | `/internal/sdk/realtime/auth` |
185 | Write | `POST` | `/trigger_instances/{slug}/upsert` |
186 | Write | `PATCH` | `/trigger_instances/manage/{triggerId}` |
187 | Write | `DELETE` | `/trigger_instances/manage/{triggerId}` |
188
189 ## Webhooks
190
191 View and manage webhook endpoints and subscriptions.
192
193 | Access | Method | Route |
194 | ------ | -------- | ------------------------------------------- |
195 | Read | `GET` | `/webhook_endpoints` |
196 | Read | `GET` | `/webhook_endpoints/{nano_id}` |
197 | Read | `GET` | `/webhook_endpoints/schema` |
198 | Read | `GET` | `/webhook_subscriptions` |
199 | Read | `GET` | `/webhook_subscriptions/{id}` |
200 | Read | `GET` | `/webhook_subscriptions/event_types` |
201 | Write | `POST` | `/webhook_endpoints` |
202 | Write | `POST` | `/webhook_endpoints/{nano_id}` |
203 | Write | `PATCH` | `/webhook_endpoints/{nano_id}` |
204 | Write | `DELETE` | `/webhook_endpoints/{nano_id}` |
205 | Write | `POST` | `/webhook_subscriptions` |
206 | Write | `PATCH` | `/webhook_subscriptions/{id}` |
207 | Write | `DELETE` | `/webhook_subscriptions/{id}` |
208 | Write | `POST` | `/webhook_subscriptions/{id}/rotate_secret` |
209
210 ## Observability
211
212 View execution logs and project usage summaries.
213
214 | Access | Method | Route |
215 | ------ | ------ | ------------------------------ |
216 | Read | `POST` | `/logs/tool_execution` |
217 | Read | `GET` | `/logs/tool_execution/{id}` |
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 grants the direct and session proxy routes below. The session proxy route also accepts **Session tool execution → Write only**. The direct `/tools/execute/proxy` route requires **Proxy execute**. Grant this permission when your application needs direct proxy access or session proxy access without session tool execution.
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>
266 <Card
267 icon={<Key />}
268 title="Authenticating to Composio"
269 href="/reference/authenticating-to-composio"
270 description="Authenticate API requests with project and organization API keys"
271 />
272 <Card
273 icon={<Key />}
274 title="Projects"
275 href="/reference/api-reference/projects"
276 description="Understand projects, project API keys, and project-scoped resources"
277 />
278 <Card
279 icon={<Terminal />}
280 title="Proxy execute"
281 href="/reference/api-reference/tools"
282 description="Call connected account APIs through the raw proxy path"
283 />
284 <Card
285 icon={<Monitor />}
286 title="Observability"
287 href="/reference/api-reference/logs"
288 description="Inspect tool execution logs and usage summaries"
289 />
290 </Cards>