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: 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> |