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: Authentication |
| 3 | description: How to authenticate with Composio APIs using project and organization API keys |
| 4 | keywords: [API authentication, API key, x-api-key, x-org-api-key, 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 | ## Project API key |
| 10 | |
| 11 | A project API key authenticates to one project with full access. Send it in the `x-api-key` header. |
| 12 | |
| 13 | 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. |
| 14 | |
| 15 | ## Organization API key |
| 16 | |
| 17 | An organization API key authenticates across every project in your organization. Send it in the `x-org-api-key` header. |
| 18 | |
| 19 | Get it from the dashboard: open **Organization Settings → General Settings** and copy a token under **Organization Access Tokens**. |
| 20 | |
| 21 | ## Using the API key |
| 22 | |
| 23 | Include your API key in the request header: |
| 24 | |
| 25 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 26 | <Tab value="Python"> |
| 27 | ```python |
| 28 | from composio import Composio |
| 29 | |
| 30 | composio = Composio() |
| 31 | print(composio.client.get("/api/v3/tools", cast_to=object)) |
| 32 | ``` |
| 33 | </Tab> |
| 34 | <Tab value="TypeScript"> |
| 35 | ```typescript |
| 36 | import { Composio } from '@composio/core'; |
| 37 | |
| 38 | const composio = new Composio(); |
| 39 | console.log(await composio.getClient().get<unknown>('/api/v3/tools')); |
| 40 | ``` |
| 41 | </Tab> |
| 42 | <Tab value="API"> |
| 43 | ```bash |
| 44 | curl -X GET https://backend.composio.dev/api/v3/tools \ |
| 45 | -H "x-api-key: $COMPOSIO_API_KEY" |
| 46 | ``` |
| 47 | </Tab> |
| 48 | </Tabs> |
| 49 | |
| 50 | For organization-level endpoints: |
| 51 | |
| 52 | The Python SDK also requires `COMPOSIO_API_KEY` to initialize. These raw calls explicitly send the organization header for the historical v3 route. |
| 53 | |
| 54 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 55 | <Tab value="Python"> |
| 56 | ```python |
| 57 | import os |
| 58 | from composio import Composio |
| 59 | |
| 60 | composio = Composio() |
| 61 | projects = composio.client.get( |
| 62 | "/api/v3/org/owner/project/list", |
| 63 | cast_to=object, |
| 64 | headers={"x-api-key": None, "x-org-api-key": os.environ["COMPOSIO_ORG_API_KEY"]}, |
| 65 | ) |
| 66 | print(projects) |
| 67 | ``` |
| 68 | </Tab> |
| 69 | <Tab value="TypeScript"> |
| 70 | ```typescript |
| 71 | import { Composio } from '@composio/core'; |
| 72 | |
| 73 | const composio = new Composio({ |
| 74 | apiKey: null, |
| 75 | userApiKey: null, |
| 76 | orgApiKey: process.env.COMPOSIO_ORG_API_KEY, |
| 77 | }); |
| 78 | console.log(await composio.getClient().get<unknown>('/api/v3/org/owner/project/list')); |
| 79 | ``` |
| 80 | </Tab> |
| 81 | <Tab value="API"> |
| 82 | ```bash |
| 83 | curl -X GET https://backend.composio.dev/api/v3/org/owner/project/list \ |
| 84 | -H "x-org-api-key: $COMPOSIO_ORG_API_KEY" |
| 85 | ``` |
| 86 | </Tab> |
| 87 | </Tabs> |
| 88 | |
| 89 | <Cards> |
| 90 | <Card title="Errors" href="/reference/v3/errors"> |
| 91 | Understanding API error responses |
| 92 | </Card> |
| 93 | <Card title="Rate Limits" href="/reference/v3/rate-limits"> |
| 94 | API rate limits by plan |
| 95 | </Card> |
| 96 | </Cards> |