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 122 lines 6.37 KB
Raw
1 ---
2 title: Design a B2B agent with Composio
3 description: Structure tenants, members, projects, sessions, and connections for a B2B agent
4 keywords: [b2b agent, multi tenant, workspace, organization, users, projects]
5 ---
6
7 A B2B agent serves organizations with multiple members. Before writing integration code, decide who owns each app connection: an individual member or the customer workspace. That decision determines the Composio user ID and access model.
8
9 ## Choose the connection owner
10
11 | Model | Use it when | Composio user ID example |
12 |---|---|---|
13 | Member-owned | Each member connects and acts through their own account | `org_42:user_7` |
14 | Workspace-owned | The organization connects one shared service account or integration | `org_42:integration` |
15
16 Use globally unique, immutable IDs. Prefixing your member ID with the workspace ID makes the tenant boundary explicit even when member IDs are only unique inside one workspace.
17
18 <Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
19 <Tab value="Python">
20 ```python
21 from composio import Composio
22
23 composio = Composio()
24
25 workspace_id = "org_42"
26 member_id = "user_7"
27 composio_user_id = f"{workspace_id}:{member_id}"
28
29 session = composio.sessions.create(
30 user_id=composio_user_id,
31 toolkits=["slack", "salesforce"],
32 )
33 tools = session.tools()
34 ```
35 </Tab>
36 <Tab value="TypeScript">
37 ```typescript
38 import { Composio } from "@composio/core";
39
40 const composio = new Composio();
41
42 const workspaceId = "org_42";
43 const memberId = "user_7";
44 const composioUserId = `${workspaceId}:${memberId}`;
45
46 const session = await composio.create(composioUserId, {
47 toolkits: ["slack", "salesforce"],
48 });
49 const tools = await session.tools();
50 ```
51 </Tab>
52 <Tab value="API">
53 ```bash
54 curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
55 -H "x-api-key: $COMPOSIO_API_KEY" \
56 -H "Content-Type: application/json" \
57 -d '{
58 "user_id": "org_42:user_7",
59 "toolkits": { "enable": ["slack", "salesforce"] }
60 }'
61 ```
62 </Tab>
63 </Tabs>
64
65 <Callout type="warn" title="Do not collapse every member into one tenant ID">
66 If members should use separate accounts, do not create all sessions with only the workspace ID. That would place their connections in the same user scope. Use a member-scoped ID and enforce your product's workspace authorization before creating or restoring a session.
67 </Callout>
68
69 ## Start with one project per environment
70
71 Use one Composio project for each application environment, such as development, staging, and production. Keep the tenant boundary in your application and `user_id` model.
72
73 Create a separate project for a customer only when you need a hard operational boundary, such as:
74
75 - Independent API keys, auth configs, branding, or webhooks
76 - Contractual or regulatory isolation
77 - Customer-specific provider credentials or infrastructure
78 - Separate usage and administration controlled by that customer
79
80 Project-per-customer isolation adds provisioning, credential management, and operational overhead. It is usually unnecessary for the first version of a multi-tenant product.
81
82 ## Model workspace-owned connections explicitly
83
84 For an organization-wide service account, create a dedicated integration identity such as `org_42:integration`. Do not reuse a real member's identity, because the connection should survive membership changes.
85
86 Your application remains responsible for deciding which members may ask the workspace-owned agent to act. Resolve the workspace, verify the member's role, then create or restore the session for the integration identity.
87
88 [Shared connections](/docs/extending-sessions/shared-connections) are available for cases where one connected account must be exposed to a controlled list of Composio users. They are an experimental, explicit access-control feature, not the default tenant model. Pin and test the SDK version before making shared connections part of a production tenant model.
89
90 ## Choose the customer's authentication model
91
92 Review the [table of controls](/docs/security/token-custody#choose-your-controls) before choosing OAuth app ownership, credential custody, deployment, and retention. Your application still authorizes each member's access to member-owned and workspace-owned connections.
93
94 Start with managed auth when Composio's provider app and scopes fit the product. Use [custom auth configs](/docs/authentication/custom-app-vs-managed-app) when your product needs its own OAuth branding, scopes, provider quotas, or self-hosted instances.
95
96 If each customer supplies different OAuth credentials, create and manage auth configs programmatically, then assign the right config when creating that customer's sessions. See [Programmatic auth configs](/docs/authentication/programmatic-auth-configs).
97
98 For a fully branded connection flow, combine custom OAuth credentials with [white-labeling](/docs/authentication/white-labeling-authentication).
99
100 ## Route events back to the right tenant
101
102 Store your workspace and member mapping next to the Composio user and connected-account IDs. When a trigger event arrives, resolve that mapping before running customer-specific work. Your webhook handler must also enforce any tenant or role checks required by your product.
103
104 See [Subscribing to trigger events](/docs/setting-up-triggers/subscribing-to-events) for webhook setup and verification.
105
106 ## Before you launch
107
108 - Test two members in the same workspace and two members in different workspaces.
109 - Confirm a removed member can no longer invoke workspace-owned connections.
110 - Keep development, staging, and production credentials separate.
111 - Define who can create, replace, or delete a workspace-owned connection.
112 - Test a real trigger event and verify it maps to the expected workspace.
113 - Inspect representative tool calls in [Logs](/reference/api-reference/logs).
114
115 ## Next
116
117 <Cards>
118 <Card title="Managed auth for your own tools" href="/docs/authentication/managed-auth-for-custom-tools" description="Keep your tool definitions and business logic while Composio authenticates provider requests." />
119 <Card title="Build a consumer agent" href="/docs/consumer-agents" description="Use a simpler per-person identity and connection model." />
120 <Card title="White-label authentication" href="/docs/authentication/white-labeling-authentication" description="Brand Connect Links, consent screens, domains, and callbacks." />
121 <Card title="Move to production" href="/docs/production-readiness" description="Review identity, auth, security, logging, and trigger decisions." />
122 </Cards>