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 22, 13:15 UTC
docs: remove multitenancy/organization content
Simplified user-management.mdx to focus on individual user management only: - Removed Organization IDs section - Removed Organization-Based Application example - Removed Hybrid Pattern section - Updated users-and-sessions.mdx to remove teams/orgs reference 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Sushmithamallesh committed
Jan 22, 2026 at 23:21 UTC
5c1d35f3661a806f9b086af02570dc9c46bc6e73
2 files changed
+8
-210
docs/content/docs/user-management.mdx
+7
-209
@@ -8,33 +8,15 @@ keywords: [user id, multi-user]
8
9
User IDs determine whose connected accounts and data you're accessing in Composio. Every tool execution, connection authorization, and account operation requires a `userId` parameter that identifies which context to use.
10
11
-User IDs act as containers that group connected accounts together across toolkits. Depending on your application, you can use User IDs to represent an individual user, a team, or an entire organization.
11
+User IDs act as containers that group connected accounts together across toolkits. Each user connects and manages their own accounts.
12
13
-## Quick Decision Guide
13
+## Choosing User IDs
14
15
-**How do users access connected accounts in your app?**
15
+**Recommended:** Database UUID or primary key (`user.id`)
16
17
-- **Each user connects their own personal accounts?**
18
- Use User IDs
19
- *Use your database UUID or primary key (e.g., `user.id`)*
20
- *Example: Users connect their personal Gmail, GitHub*
17
+**Acceptable:** Unique username (`user.username`)
18
22
-- **Teams share the same connected accounts?**
23
- Use Organization IDs
24
- *Use your organization UUID or primary key (e.g., `organization.id`)*
25
- *Example: Company Slack workspace*
26
-
27
-## Patterns
28
-
29
-### User IDs (Individual Accounts)
30
-
31
-In production applications with multiple users, where each user connects and manages their own accounts.
32
-
33
-**Choosing User IDs:**
34
-
35
-- Recommended: Database UUID or primary key (`user.id`)
36
-- Acceptable: Unique username (`user.username`)
37
-- Avoid: Email addresses (emails can change)
19
+**Avoid:** Email addresses (emails can change)
20
21
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
22
<Tab value="Python">
@@ -82,64 +64,6 @@ const result = await composio.tools.execute('GITHUB_GET_REPO', {
64
Never use 'default' as a User ID in production with users. This could expose other users' data.
65
</Callout>
66
85
-### Organization IDs (Team Accounts)
86
-
87
-For applications where teams share connections - one admin connects accounts, all team members use them.
88
-
89
-**When to use:**
90
-- Team tools: Slack, Microsoft Teams, Jira
91
-- Shared accounts: support@company.com, company GitHub org
92
-- Enterprise apps: IT manages connections for all employees
93
-
94
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
95
- <Tab value="Python">
96
-```python
97
-# Use the organization ID as userId
98
-user_id = organization.id # e.g., "org_550e8400"
99
-
100
-# All users in the organization share the same connected accounts
101
-tools = composio.tools.get(
102
- user_id=user_id,
103
- toolkits=["SLACK"],
104
-)
105
-
106
-# Execute tools in the organization context
107
-result = composio.tools.execute(
108
- "SLACK_SEND_MESSAGE",
109
- user_id=user_id,
110
- arguments={
111
- "channel": '#general',
112
- "text": 'Hello from the team!'
113
- }
114
-)
115
-```
116
- </Tab>
117
- <Tab value="TypeScript">
118
-```typescript
119
-import { Composio } from '@composio/core';
120
-const composio = new Composio({ apiKey: 'your_api_key' });
121
-declare const organization: { id: string };
122
-// ---cut---
123
-// Use the organization ID as userId
124
-const userId = organization.id; // e.g., "org_550e8400"
125
-
126
-// All users in the organization share the same connected accounts
127
-const tools = await composio.tools.get(userId, {
128
- toolkits: ['slack'],
129
-});
130
-
131
-// Execute tools in the organization context
132
-const result = await composio.tools.execute('SLACK_SEND_MESSAGE', {
133
- userId: userId,
134
- arguments: {
135
- channel: '#general',
136
- text: 'Hello from the team!',
137
- },
138
-});
139
-```
140
- </Tab>
141
-</Tabs>
142
-
67
## Multiple Connected Accounts
68
69
A single User ID can have multiple connected accounts for the same toolkit. For example, a user might connect both their personal and work Gmail accounts.
@@ -153,79 +77,9 @@ A single User ID can have multiple connected accounts for the same toolkit. For
77
- **Explicit:** Specify the Connected Account ID to target a specific account
78
- **Default:** If no Connected Account ID is provided, the most recently connected account is used
79
156
-## Examples
157
-
158
-### Organization-Based Application
80
+## Example: Multi-User Application
81
160
-In B2B applications, typically an admin connects accounts once and all team members share access. Here's a complete implementation:
161
-
162
-**Key concepts:**
163
-- Admin performs the OAuth connection using organization ID
164
-- All team members execute tools using the same organization ID
165
-- Permission checks ensure users can only access their organization's connections
166
-
167
-```typescript
168
-import { ConnectionRequest } from '@composio/core';
169
-declare function storeConnectionRequest(orgId: string, adminId: string, req: ConnectionRequest): Promise<void>;
170
-declare function userCanSendMessages(userId: string, orgId: string): Promise<boolean>;
171
-declare const app: { post: (path: string, handler: (req: any, res: any) => Promise<any>) => void };
172
-// ---cut---
173
-import { Composio } from '@composio/core';
174
-const composio = new Composio({
175
- apiKey: process.env.COMPOSIO_API_KEY,
176
-});
177
-
178
-// 1. Admin connects Slack for the entire organization
179
-async function connectOrganizationToSlack(organizationId: string, adminUserId: string) {
180
- // Use organization ID as userId in Composio
181
- const connectionRequest = await composio.toolkits.authorize(organizationId, 'slack');
182
-
183
- // Store the connection request for the admin to complete
184
- await storeConnectionRequest(organizationId, adminUserId, connectionRequest);
185
-
186
- return connectionRequest.redirectUrl;
187
-}
188
-
189
-// 2. Any user in the organization can use the connected tools
190
-async function sendSlackMessage(organizationId: string, channel: string, message: string) {
191
- return await composio.tools.execute('SLACK_SEND_MESSAGE', {
192
- userId: organizationId, // organization ID, not individual user ID
193
- arguments: {
194
- channel: channel,
195
- text: message,
196
- },
197
- });
198
-}
199
-
200
-// 3. Check if organization has required connections
201
-async function getOrganizationTools(organizationId: string) {
202
- return await composio.tools.get(organizationId, {
203
- toolkits: ['slack', 'github', 'jira'],
204
- });
205
-}
206
-
207
-// Usage in your API endpoint
208
-app.post('/api/slack/message', async (req, res) => {
209
- const { channel, message } = req.body;
210
- const organizationId = req.user.organizationId; // Get from your auth system
211
-
212
- // Verify user has permission to send messages for this organization
213
- if (!(await userCanSendMessages(req.user.id, organizationId))) {
214
- return res.status(403).json({ error: 'Insufficient permissions' });
215
- }
216
-
217
- try {
218
- const result = await sendSlackMessage(organizationId, channel, message);
219
- res.json(result.data);
220
- } catch (error) {
221
- res.status(500).json({ error: 'Failed to send message' });
222
- }
223
-});
224
-```
225
-
226
-### Multi-User Application
227
-
228
-In B2C applications, each user connects and manages their own accounts. Every user goes through their own OAuth flow and their data remains completely isolated.
82
+In applications with multiple users, each user connects and manages their own accounts. Every user goes through their own OAuth flow and their data remains completely isolated.
83
84
**Key concepts:**
85
- Each user authorizes their own accounts using their unique user ID
@@ -278,65 +132,9 @@ app.get('/api/github/repos', async (req, res) => {
132
133
**Data isolation**: Composio ensures each userId's connections and data are completely separate. User A can never access User B's repositories.
134
281
-### Hybrid Pattern
282
-
283
-Many applications need both personal and team resources. Users might connect their personal Gmail while sharing the company Slack workspace.
284
-
285
-**Common scenarios:**
286
-- Personal calendars + shared project management
287
-- Individual GitHub accounts + organization repositories
288
-
289
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
290
- <Tab value="Python">
291
-```python
292
-# Wrong: Using individual user ID for org-connected tool
293
-user_tools = composio.tools.get(
294
- user_id="user_123", # Individual user ID
295
- toolkits=["slack"] # Fails - Slack is connected at org level
296
-)
297
-
298
-# Correct: Match the ID type to how the tool was connected
299
-user_personal_tools = composio.tools.get(
300
- user_id="user_123", # Individual user ID
301
- toolkits=["gmail"] # User's personal Gmail
302
-)
303
-
304
-org_shared_tools = composio.tools.get(
305
- user_id="org_123", # Organization ID
306
- toolkits=["slack", "jira"] # Organization's shared tools
307
-)
308
-```
309
- </Tab>
310
- <Tab value="TypeScript">
311
-```typescript
312
-import { Composio } from '@composio/core';
313
-const composio = new Composio({ apiKey: 'your_api_key' });
314
-declare const req: { user: { id: string; organizationId: string } };
315
-// ---cut---
316
-// Wrong: Using individual user ID for org-connected tool
317
-const userTools = await composio.tools.get(req.user.id, {
318
- toolkits: ['slack'], // Fails - Slack is connected at org level
319
-});
320
-
321
-// Correct: Match the ID type to how the tool was connected
322
-const userPersonalTools = await composio.tools.get(req.user.id, {
323
- toolkits: ['gmail'], // User's personal Gmail
324
-});
325
-
326
-const orgSharedTools = await composio.tools.get(req.user.organizationId, {
327
- toolkits: ['slack', 'jira'], // Organization's shared tools
328
-});
329
-```
330
- </Tab>
331
-</Tabs>
332
-
333
-Remember: The userId must match how the account was connected. If admin connected Slack with org ID, all members must use org ID to access it.
334
-
135
## Best Practices
136
337
-**Your responsibilities:**
137
- Pass the correct User ID for each user
339
-- Verify user permissions before executing organization tools
138
- Never use 'default' in production with multiple users
139
- Keep User IDs consistent across your application and Composio
140
- Use stable identifiers that won't change over time
docs/content/docs/users-and-sessions.mdx
+1
-1
@@ -4,7 +4,7 @@ description: Understand how Tool Router scopes tools and connections per user
4
keywords: [session, user id, enable toolkits, disable toolkits]
5
---
6
7
-A **user ID** is an identifier from your system (database ID, UUID, or any unique string) that scopes connected accounts and tool access to a specific user. User IDs can represent individuals, teams, or organizations. See [User Management](/docs/user-management) for patterns.
7
+A **user ID** is an identifier from your system (database ID, UUID, or any unique string) that scopes connected accounts and tool access to a specific user. See [User Management](/docs/user-management) for best practices.
8
9
A **session** is an ephemeral configuration that combines:
10
- Which user's connected accounts to use