Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
mdx 262 lines 11.1 KB
Raw
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>