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
| 1 | --- |
| 2 | title: Overview |
| 3 | description: Authenticate requests to the Composio API with an API key |
| 4 | keywords: [API authentication, API key, x-api-key, x-org-api-key, x-user-api-key, user api key, scoped api key, consumer project, Composio authentication, authorization] |
| 5 | --- |
| 6 | |
| 7 | Every Composio API request authenticates with an API key. Send the key in a request header and Composio resolves it to your project or organization. |
| 8 | |
| 9 | Composio has four kinds of API key. They share the same authentication flow and differ in what they can reach. |
| 10 | |
| 11 | | Key | Header | Scope | |
| 12 | | --- | --- | --- | |
| 13 | | Project API key | `x-api-key` | Full access to a single project. | |
| 14 | | Organization API key | `x-org-api-key` | Access across every project in your organization. | |
| 15 | | Scoped project API key <span style={{ color: '#059669' }}>**· New**</span> | `x-api-key` | A chosen subset of a single project's resources. | |
| 16 | | User API key | `x-user-api-key` | Sessions and consumer routes, as a member of your organization. | |
| 17 | |
| 18 | Send one credential per request, in the header that matches its kind. A user API key (`uak_...`) sent as `x-api-key` gets its own `401` that names the mismatch without echoing the key. |
| 19 | |
| 20 | ## Project API key |
| 21 | |
| 22 | A project API key authenticates to one project with full access. Use it for most application code. |
| 23 | |
| 24 | Get it from the dashboard: sign in to [composio.dev](https://composio.dev), open **Settings → Project Settings**, and copy the key from the **API Keys** section. |
| 25 | |
| 26 | For an unattended coding agent with no human available to log in, use the [agent authentication guide](/docs/agent-setup/unattended-authentication) to provision a Composio account with `composio login --agent`, configure a project API key, and verify a live tool call. |
| 27 | |
| 28 | Send it in the `x-api-key` header: |
| 29 | |
| 30 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 31 | <Tab value="Python"> |
| 32 | ```python |
| 33 | from composio import Composio |
| 34 | |
| 35 | composio = Composio() |
| 36 | print(composio.client.tools.list()) |
| 37 | ``` |
| 38 | </Tab> |
| 39 | <Tab value="TypeScript"> |
| 40 | ```typescript |
| 41 | import { Composio } from '@composio/core'; |
| 42 | |
| 43 | const composio = new Composio(); |
| 44 | console.log(await composio.getClient().get<unknown>('/api/v3.1/tools')); |
| 45 | ``` |
| 46 | </Tab> |
| 47 | <Tab value="API"> |
| 48 | ```bash |
| 49 | curl -X GET https://backend.composio.dev/api/v3.1/tools \ |
| 50 | -H "x-api-key: $COMPOSIO_API_KEY" |
| 51 | ``` |
| 52 | </Tab> |
| 53 | </Tabs> |
| 54 | |
| 55 | ## Organization API key |
| 56 | |
| 57 | An organization API key authenticates across every project in your organization. Use it for organization-level endpoints. |
| 58 | |
| 59 | Get it from the dashboard: open **Organization Settings → General Settings** and copy a token under **Organization Access Tokens**. |
| 60 | |
| 61 | Send it in the `x-org-api-key` header: |
| 62 | |
| 63 | The Python SDK also requires `COMPOSIO_API_KEY` to initialize; the generated organization endpoint selects `COMPOSIO_ORG_API_KEY` for this request. |
| 64 | |
| 65 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 66 | <Tab value="Python"> |
| 67 | ```python |
| 68 | import os |
| 69 | from composio import Composio |
| 70 | |
| 71 | composio = Composio(org_api_key=os.environ["COMPOSIO_ORG_API_KEY"]) |
| 72 | print(composio.client.org.owner.project.list()) |
| 73 | ``` |
| 74 | </Tab> |
| 75 | <Tab value="TypeScript"> |
| 76 | ```typescript |
| 77 | import { Composio } from '@composio/core'; |
| 78 | |
| 79 | const composio = new Composio({ |
| 80 | apiKey: null, |
| 81 | userApiKey: null, |
| 82 | orgApiKey: process.env.COMPOSIO_ORG_API_KEY, |
| 83 | }); |
| 84 | console.log(await composio.getClient().get<unknown>('/api/v3.1/org/owner/project/list')); |
| 85 | ``` |
| 86 | </Tab> |
| 87 | <Tab value="API"> |
| 88 | ```bash |
| 89 | curl -X GET https://backend.composio.dev/api/v3.1/org/owner/project/list \ |
| 90 | -H "x-org-api-key: $COMPOSIO_ORG_API_KEY" |
| 91 | ``` |
| 92 | </Tab> |
| 93 | </Tabs> |
| 94 | |
| 95 | ## Scoped project API key |
| 96 | |
| 97 | A scoped project API key authenticates to a single project but reaches only the resources you grant it — for example, executing tools without managing connected accounts. It uses the same `x-api-key` header as a default project key. |
| 98 | |
| 99 | Scope a key to the least it needs, then send it like any project key: |
| 100 | |
| 101 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 102 | <Tab value="Python"> |
| 103 | ```python |
| 104 | import os |
| 105 | from composio import Composio |
| 106 | |
| 107 | composio = Composio(api_key=os.environ["COMPOSIO_SCOPED_API_KEY"]) |
| 108 | result = composio.client.post( |
| 109 | "/api/v3.1/tools/execute/HACKERNEWS_GET_USER", |
| 110 | cast_to=object, |
| 111 | body={"arguments": {"username": "pg"}}, |
| 112 | ) |
| 113 | print(result) |
| 114 | ``` |
| 115 | </Tab> |
| 116 | <Tab value="TypeScript"> |
| 117 | ```typescript |
| 118 | import { Composio } from '@composio/core'; |
| 119 | |
| 120 | const scopedApiKey = process.env.COMPOSIO_SCOPED_API_KEY; |
| 121 | if (!scopedApiKey) throw new Error('Set COMPOSIO_SCOPED_API_KEY to a least-privilege project key'); |
| 122 | const composio = new Composio({ apiKey: scopedApiKey }); |
| 123 | const result = await composio.getClient().post<unknown>('/api/v3.1/tools/execute/HACKERNEWS_GET_USER', { |
| 124 | body: { arguments: { username: 'pg' } }, |
| 125 | }); |
| 126 | console.log(result); |
| 127 | ``` |
| 128 | </Tab> |
| 129 | <Tab value="API"> |
| 130 | ```bash |
| 131 | curl -X POST https://backend.composio.dev/api/v3.1/tools/execute/HACKERNEWS_GET_USER \ |
| 132 | -H "x-api-key: $COMPOSIO_SCOPED_API_KEY" \ |
| 133 | -H "Content-Type: application/json" \ |
| 134 | -d '{"arguments": {"username": "pg"}}' |
| 135 | ``` |
| 136 | </Tab> |
| 137 | </Tabs> |
| 138 | |
| 139 | See [Scoped project API keys](/reference/authenticating-to-composio/project-api-key-permissions) for the permission areas, access levels, and the routes each one covers. |
| 140 | |
| 141 | ## User API key |
| 142 | |
| 143 | A user API key authenticates you as a member of your organization instead of as one project. It starts with `uak_`, and `composio login` stores one in `~/.composio/user_data.json`. Send it in the `x-user-api-key` header. |
| 144 | |
| 145 | Every session route accepts a user API key as an alternative to a project key: create, retrieve, update, delete, attach, link, search, execute, tools, toolkits, mounts, and config history. Without a scope header the key addresses your developer project: |
| 146 | |
| 147 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 148 | <Tab value="Python"> |
| 149 | ```python |
| 150 | import os |
| 151 | from composio import Composio |
| 152 | |
| 153 | composio = Composio( |
| 154 | disable_api_key=True, |
| 155 | user_api_key=os.environ["COMPOSIO_USER_API_KEY"], |
| 156 | ) |
| 157 | session = composio.create(user_id="user_123", toolkits=["gmail"]) |
| 158 | print(session) |
| 159 | ``` |
| 160 | </Tab> |
| 161 | <Tab value="TypeScript"> |
| 162 | ```typescript |
| 163 | import { Composio } from '@composio/core'; |
| 164 | |
| 165 | const composio = new Composio({ |
| 166 | apiKey: null, |
| 167 | userApiKey: process.env.COMPOSIO_USER_API_KEY, |
| 168 | }); |
| 169 | const session = await composio.create('user_123', { toolkits: ['gmail'] }); |
| 170 | console.log(session); |
| 171 | ``` |
| 172 | </Tab> |
| 173 | <Tab value="API"> |
| 174 | {/* code-example: unchecked-api rule="api-key-header" operation="POST /api/v3.1/tool_router/session" field="x-api-key" reason="session routes accept x-user-api-key but OpenAPI lists only the project API-key alternative" */} |
| 175 | ```bash |
| 176 | curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \ |
| 177 | -H "x-user-api-key: $COMPOSIO_USER_API_KEY" \ |
| 178 | -H "Content-Type: application/json" \ |
| 179 | -d '{"user_id": "user_123", "toolkits": {"enable": ["gmail"]}}' |
| 180 | ``` |
| 181 | </Tab> |
| 182 | </Tabs> |
| 183 | |
| 184 | To act in your organization's consumer project, add `x-org-id` and `x-project-id`, always together and always as nano IDs (`org_...` and `proj_...`, never UUIDs). The [consumer agent guide](/docs/consumer-agents#run-sessions-in-your-organizations-consumer-project) shows how to resolve those IDs first. |
| 185 | |
| 186 | A user API key reaches every project its owner can reach, so it is the broader credential. Keep it server-side, and prefer a project API key for application code that only needs one project. |
| 187 | |
| 188 | ### Scope errors |
| 189 | |
| 190 | | Status | Meaning | |
| 191 | | --- | --- | |
| 192 | | `401` | The credential is missing or invalid, or a user key was sent as `x-api-key`. | |
| 193 | | `400` | A scope header is missing or holds a UUID instead of a nano ID. | |
| 194 | | `404` | The organization or project does not exist or is not accessible to this user. The two cases are deliberately indistinguishable. | |
| 195 | | `500` | The scope lookup itself failed. Retry, then contact support if it persists. | |
| 196 | |
| 197 | ## Choosing the key in the SDKs |
| 198 | |
| 199 | The SDKs resolve the project API key by intent, so an unexpected key never gets sent by accident. |
| 200 | |
| 201 | | `Composio` option | What the SDK sends | |
| 202 | | --- | --- | |
| 203 | | `apiKey: "ak_..."` | That key, as `x-api-key`. The environment and the CLI's stored key are not consulted. | |
| 204 | | `apiKey` omitted | `COMPOSIO_API_KEY`, then the project key stored by `composio login` in `~/.composio/user_data.json`. A stored user key (`uak_...`) is never sent as `x-api-key`; the constructor throws `ComposioAPIKeyKindError` with the value redacted. | |
| 205 | | `apiKey: null` | No project key at all. Both fallbacks are off, and the instance authenticates with the user API key you configure instead: `userApiKey`, its `COMPOSIO_USER_API_KEY` fallback, or an `x-user-api-key` entry in `defaultHeaders`. In Python, `disable_api_key=True` does the same with `user_api_key` or `COMPOSIO_USER_API_KEY`. | |
| 206 | |
| 207 | A user-only instance sends `x-user-api-key` on every request and no `x-api-key`. Only `x-user-api-key` in `defaultHeaders` counts as a credential; every other default header passes through untouched. Clones made with `createSession()` keep the credentials they were resolved with instead of re-reading the environment. |
| 208 | |
| 209 | {/* code-example: no-api reason="SDK constructor options choosing which key header the client sends" */} |
| 210 | <Tabs groupId="language" items={['Python', 'TypeScript']} persist> |
| 211 | <Tab value="Python"> |
| 212 | ```python |
| 213 | import os |
| 214 | |
| 215 | from composio import Composio |
| 216 | |
| 217 | # Project key: pass it, or omit api_key to fall back to COMPOSIO_API_KEY. |
| 218 | composio = Composio(api_key=os.environ["COMPOSIO_API_KEY"]) |
| 219 | |
| 220 | # User key only: turn the project key off and use the user key alone. |
| 221 | composio = Composio( |
| 222 | disable_api_key=True, |
| 223 | user_api_key=os.environ["COMPOSIO_USER_API_KEY"], |
| 224 | ) |
| 225 | ``` |
| 226 | </Tab> |
| 227 | <Tab value="TypeScript"> |
| 228 | ```typescript |
| 229 | import { Composio } from "@composio/core"; |
| 230 | |
| 231 | // Project key: pass it, or omit apiKey to fall back to COMPOSIO_API_KEY. |
| 232 | const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY }); |
| 233 | |
| 234 | // User key only: turn the project key off and use the user key alone. |
| 235 | // userApiKey falls back to COMPOSIO_USER_API_KEY when omitted. |
| 236 | const userScoped = new Composio({ |
| 237 | apiKey: null, |
| 238 | userApiKey: process.env.COMPOSIO_USER_API_KEY, |
| 239 | }); |
| 240 | ``` |
| 241 | </Tab> |
| 242 | </Tabs> |
| 243 | |
| 244 | <Callout type="info"> |
| 245 | Requires `@composio/core` ≥ `0.19.1` (TypeScript) or `composio` ≥ `0.22.1` (Python). In Python only an omitted `api_key` falls back to `COMPOSIO_API_KEY`; an explicit `api_key=None` raises `ApiKeyNotProvidedError`, and combining `disable_api_key=True` with an explicit `api_key` raises an error. Sessions created by a user-only SDK instance export `x-user-api-key` in their MCP config; see [What the MCP headers carry](/docs/sessions-via-mcp#what-the-mcp-headers-carry). Raw HTTP callers send the same `x-user-api-key` header themselves. |
| 246 | </Callout> |
| 247 | |
| 248 | ## Webhook secrets in responses |
| 249 | |
| 250 | Project listings and `GET /api/v3.1/auth/session/info` return `webhook_secret: null`. Read a signing secret from the [webhook subscription](/reference/api-reference/webhook-subscriptions/getWebhookSubscriptionsById) endpoints, or [rotate it](/reference/api-reference/webhook-subscriptions/postWebhookSubscriptionsByIdRotateSecret) there. |
| 251 | |
| 252 | <Cards> |
| 253 | <Card title="Scoped project API keys" href="/reference/authenticating-to-composio/project-api-key-permissions"> |
| 254 | Permission areas, access levels, and covered routes |
| 255 | </Card> |
| 256 | <Card title="Errors" href="/reference/errors"> |
| 257 | Understanding API error responses |
| 258 | </Card> |
| 259 | <Card title="Rate Limits" href="/reference/rate-limits"> |
| 260 | API rate limits by plan |
| 261 | </Card> |
| 262 | </Cards> |