@devries-cameron20 / composio Mirror · read-only
Fork 0

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, 03:37 UTC

next
mdx 89 lines 3.37 KB
Raw
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.