Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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> |