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 | Projects are Composio's multi-tenancy primitive. Every Composio account belongs to an **organization**. Inside an organization, **projects** are isolated environments that scope your API keys, connected accounts, auth configs, and webhook configurations. Resources in one project are not accessible from another. |
| 2 | |
| 3 | ```mermaid |
| 4 | graph LR |
| 5 | ORG["Organization (org_xxx)"] --- P1["Project: Production (proj_xxx)"] |
| 6 | ORG --- P2["Project: Staging (proj_xxx)"] |
| 7 | ORG --- TM["Team Members"] |
| 8 | P1 --- A1["API Keys"] |
| 9 | P1 --- A2["Connected Accounts"] |
| 10 | P1 --- A3["Auth Configs"] |
| 11 | P1 --- A4["Webhook Config"] |
| 12 | P2 --- B1["..."] |
| 13 | ``` |
| 14 | |
| 15 | Common reasons to use multiple projects: |
| 16 | |
| 17 | - **Separate environments**: keep production and staging isolated |
| 18 | - **Separate products**: keep resources for different apps independent |
| 19 | - **Client isolation**: give each client their own project with separate credentials and data |
| 20 | |
| 21 | ## Managing projects |
| 22 | |
| 23 | Manage projects from the [dashboard](https://dashboard.composio.dev/~/org/) or via the API using an **organization API key** (`x-org-api-key`). |
| 24 | |
| 25 | <Callout type="info"> |
| 26 | Project management endpoints use the `x-org-api-key` header, not the regular `x-api-key`. Find your org API key in the dashboard under **Settings > Organization**. |
| 27 | </Callout> |
| 28 | |
| 29 | There is no limit on the number of projects per organization. Project names must be unique within the organization. Create a project with `should_create_api_key: true` to get an API key back in the response: |
| 30 | |
| 31 | The Python SDK also needs `COMPOSIO_API_KEY` to initialize. Its generated organization client selects the organization key for this operation. |
| 32 | |
| 33 | <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist> |
| 34 | <Tab value="Python"> |
| 35 | ```python |
| 36 | import os |
| 37 | from composio import Composio |
| 38 | |
| 39 | composio = Composio(org_api_key=os.environ["COMPOSIO_ORG_API_KEY"]) |
| 40 | project = composio.client.org.owner.project.create( |
| 41 | name="my-staging-project", |
| 42 | should_create_api_key=True, |
| 43 | ) |
| 44 | print(project) |
| 45 | ``` |
| 46 | </Tab> |
| 47 | <Tab value="TypeScript"> |
| 48 | ```typescript |
| 49 | import { Composio } from '@composio/core'; |
| 50 | |
| 51 | const composio = new Composio({ |
| 52 | apiKey: null, |
| 53 | userApiKey: null, |
| 54 | orgApiKey: process.env.COMPOSIO_ORG_API_KEY, |
| 55 | }); |
| 56 | const project = await composio.getClient().post<unknown>('/api/v3.1/org/owner/project/new', { |
| 57 | body: { name: 'my-staging-project', should_create_api_key: true }, |
| 58 | }); |
| 59 | console.log(project); |
| 60 | ``` |
| 61 | </Tab> |
| 62 | <Tab value="API"> |
| 63 | ```bash |
| 64 | curl -X POST https://backend.composio.dev/api/v3.1/org/owner/project/new \ |
| 65 | -H "x-org-api-key: $COMPOSIO_ORG_API_KEY" \ |
| 66 | -H "Content-Type: application/json" \ |
| 67 | -d '{ |
| 68 | "name": "my-staging-project", |
| 69 | "should_create_api_key": true |
| 70 | }' |
| 71 | ``` |
| 72 | </Tab> |
| 73 | </Tabs> |
| 74 | |
| 75 | ```json |
| 76 | { |
| 77 | "id": "proj_abc123xyz456", |
| 78 | "name": "my-staging-project", |
| 79 | "api_key": "ak_abc123xyz456" |
| 80 | } |
| 81 | ``` |
| 82 | |
| 83 | The list endpoint supports pagination with `limit` and `cursor`; getting a project by ID returns the full project object including its API keys. |
| 84 | |
| 85 | ## Project settings |
| 86 | |
| 87 | Each project has settings that control security, logging, and display behavior. The project detail endpoints return current configuration for inspection. Use **Settings > Project Settings** in the [dashboard](https://dashboard.composio.dev/~/project/settings/general) to update project settings. |
| 88 | |
| 89 | Notable security setting: `require_mcp_api_key`, when `true`, requires MCP server requests to include a valid `x-api-key` header. This defaults to `true` for organizations created on or after March 5, 2026. |