1
+---
2
+title: User Management
3
+description: Manage users and their connected accounts
4
+---
5
+
6
+## What are User IDs?
7
+
8
+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.
9
+
10
+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
+
12
+## Quick Decision Guide
13
+
14
+**How do users access connected accounts in your app?**
15
+
16
+- **Each user connects their own personal accounts?**
17
+ Use User IDs
18
+ *Use your database UUID or primary key (e.g., `user.id`)*
19
+ *Example: Users connect their personal Gmail, GitHub*
20
+
21
+- **Teams share the same connected accounts?**
22
+ Use Organization IDs
23
+ *Use your organization UUID or primary key (e.g., `organization.id`)*
24
+ *Example: Company Slack workspace*
25
+
26
+## Patterns
27
+
28
+### User IDs (Individual Accounts)
29
+
30
+In production applications with multiple users, where each user connects and manages their own accounts.
31
+
32
+**Choosing User IDs:**
33
+
34
+- Recommended: Database UUID or primary key (`user.id`)
35
+- Acceptable: Unique username (`user.username`)
36
+- Avoid: Email addresses (emails can change)
37
+
38
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
39
+ <Tab value="Python">
40
+```python
41
+# Use your database's user ID (UUID, primary key, etc.)
42
+user_id = user.id; # e.g., "550e8400-e29b-41d4-a716-446655440000"
43
+
44
+tools = composio.tools.get(
45
+ user_id=user_id,
46
+ toolkits=["GITHUB"],
47
+)
48
+
49
+result = composio.tools.execute(
50
+ "GITHUB_GET_REPO",
51
+ user_id=user_id,
52
+ arguments={
53
+ "owner": 'example',
54
+ "repo": 'repo'
55
+ }
56
+)
57
+```
58
+ </Tab>
59
+ <Tab value="TypeScript">
60
+```typescript
61
+// Use your database's user ID (UUID, primary key, etc.)
62
+const userId = user.id; // e.g., "550e8400-e29b-41d4-a716-446655440000"
63
+
64
+const tools = await composio.tools.get(userId, {
65
+ toolkits: ['github'],
66
+});
67
+
68
+const result = await composio.tools.execute('GITHUB_GET_REPO', {
69
+ userId: userId,
70
+ arguments: { owner: 'example', repo: 'repo' },
71
+});
72
+```
73
+ </Tab>
74
+</Tabs>
75
+
76
+<Callout type="warn">
77
+Never use 'default' as a User ID in production with users. This could expose other users' data.
78
+</Callout>
79
+
80
+### Organization IDs (Team Accounts)
81
+
82
+For applications where teams share connections - one admin connects accounts, all team members use them.
83
+
84
+**When to use:**
85
+- Team tools: Slack, Microsoft Teams, Jira
86
+- Shared accounts: support@company.com, company GitHub org
87
+- Enterprise apps: IT manages connections for all employees
88
+
89
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
90
+ <Tab value="Python">
91
+```python
92
+# Use the organization ID as userId
93
+user_id = organization.id # e.g., "org_550e8400"
94
+
95
+# All users in the organization share the same connected accounts
96
+tools = composio.tools.get(
97
+ user_id=user_id,
98
+ toolkits=["SLACK"],
99
+)
100
+
101
+# Execute tools in the organization context
102
+result = composio.tools.execute(
103
+ "SLACK_SEND_MESSAGE",
104
+ user_id=user_id,
105
+ arguments={
106
+ "channel": '#general',
107
+ "text": 'Hello from the team!'
108
+ }
109
+)
110
+```
111
+ </Tab>
112
+ <Tab value="TypeScript">
113
+```typescript
114
+// Use the organization ID as userId
115
+const userId = organization.id; // e.g., "org_550e8400"
116
+
117
+// All users in the organization share the same connected accounts
118
+const tools = await composio.tools.get(userId, {
119
+ toolkits: ['slack'],
120
+});
121
+
122
+// Execute tools in the organization context
123
+const result = await composio.tools.execute('SLACK_SEND_MESSAGE', {
124
+ userId: userId,
125
+ arguments: {
126
+ channel: '#general',
127
+ text: 'Hello from the team!',
128
+ },
129
+});
130
+```
131
+ </Tab>
132
+</Tabs>
133
+
134
+## Multiple Connected Accounts
135
+
136
+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.
137
+
138
+**Key concepts:**
139
+- Each connected account gets a unique Connected Account ID
140
+- Multiple accounts can exist under the same User ID for any toolkit
141
+- You can specify which account to use when executing tools
142
+
143
+**Account selection:**
144
+- **Explicit:** Specify the Connected Account ID to target a specific account
145
+- **Default:** If no Connected Account ID is provided, the most recently connected account is used
146
+
147
+## Examples
148
+
149
+### Organization-Based Application
150
+
151
+In B2B applications, typically an admin connects accounts once and all team members share access. Here's a complete implementation:
152
+
153
+**Key concepts:**
154
+- Admin performs the OAuth connection using organization ID
155
+- All team members execute tools using the same organization ID
156
+- Permission checks ensure users can only access their organization's connections
157
+
158
+```typescript
159
+import { Composio } from '@composio/core';
160
+const composio = new Composio({
161
+ apiKey: process.env.COMPOSIO_API_KEY,
162
+});
163
+
164
+// 1. Admin connects Slack for the entire organization
165
+async function connectOrganizationToSlack(organizationId: string, adminUserId: string) {
166
+ // Use organization ID as userId in Composio
167
+ const connectionRequest = await composio.toolkits.authorize(organizationId, 'slack');
168
+
169
+ // Store the connection request for the admin to complete
170
+ await storeConnectionRequest(organizationId, adminUserId, connectionRequest);
171
+
172
+ return connectionRequest.redirectUrl;
173
+}
174
+
175
+// 2. Any user in the organization can use the connected tools
176
+async function sendSlackMessage(organizationId: string, channel: string, message: string) {
177
+ return await composio.tools.execute('SLACK_SEND_MESSAGE', {
178
+ userId: organizationId, // organization ID, not individual user ID
179
+ arguments: {
180
+ channel: channel,
181
+ text: message,
182
+ },
183
+ });
184
+}
185
+
186
+// 3. Check if organization has required connections
187
+async function getOrganizationTools(organizationId: string) {
188
+ return await composio.tools.get(organizationId, {
189
+ toolkits: ['slack', 'github', 'jira'],
190
+ });
191
+}
192
+
193
+// Usage in your API endpoint
194
+app.post('/api/slack/message', async (req, res) => {
195
+ const { channel, message } = req.body;
196
+ const organizationId = req.user.organizationId; // Get from your auth system
197
+
198
+ // Verify user has permission to send messages for this organization
199
+ if (!(await userCanSendMessages(req.user.id, organizationId))) {
200
+ return res.status(403).json({ error: 'Insufficient permissions' });
201
+ }
202
+
203
+ try {
204
+ const result = await sendSlackMessage(organizationId, channel, message);
205
+ res.json(result.data);
206
+ } catch (error) {
207
+ res.status(500).json({ error: 'Failed to send message' });
208
+ }
209
+});
210
+```
211
+
212
+### Multi-User Application
213
+
214
+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.
215
+
216
+**Key concepts:**
217
+- Each user authorizes their own accounts using their unique user ID
218
+- Connections are isolated - users can only access their own connected accounts
219
+- No permission checks needed since users only access their own data
220
+
221
+```typescript
222
+import { Composio } from '@composio/core';
223
+const composio = new Composio({
224
+ apiKey: process.env.COMPOSIO_API_KEY,
225
+});
226
+
227
+// 1. User initiates GitHub connection
228
+async function connectUserToGitHub(userId: string) {
229
+ const connectionRequest = await composio.toolkits.authorize(userId, 'github');
230
+ return connectionRequest.redirectUrl;
231
+}
232
+
233
+// 2. Get user's connected GitHub tools
234
+async function getUserGitHubTools(userId: string) {
235
+ return await composio.tools.get(userId, {
236
+ toolkits: ['github'],
237
+ });
238
+}
239
+
240
+// 3. Execute tool for specific user
241
+async function getUserRepos(userId: string) {
242
+ return await composio.tools.execute('GITHUB_LIST_REPOS', {
243
+ userId: userId,
244
+ arguments: {
245
+ per_page: 10,
246
+ },
247
+ });
248
+}
249
+
250
+// Usage in your API endpoint
251
+app.get('/api/github/repos', async (req, res) => {
252
+ const userId = req.user.id; // Get from your auth system
253
+
254
+ try {
255
+ const repos = await getUserRepos(userId);
256
+ res.json(repos.data);
257
+ } catch (error) {
258
+ res.status(500).json({ error: 'Failed to fetch repos' });
259
+ }
260
+});
261
+```
262
+
263
+**Data isolation**: Composio ensures each userId's connections and data are completely separate. User A can never access User B's repositories.
264
+
265
+### Hybrid Pattern
266
+
267
+Many applications need both personal and team resources. Users might connect their personal Gmail while sharing the company Slack workspace.
268
+
269
+**Common scenarios:**
270
+- Personal calendars + shared project management
271
+- Individual GitHub accounts + organization repositories
272
+
273
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
274
+ <Tab value="Python">
275
+```python
276
+# Wrong: Using individual user ID for org-connected tool
277
+user_tools = composio.tools.get(
278
+ user_id="user_123", # Individual user ID
279
+ toolkits=["slack"] # Fails - Slack is connected at org level
280
+)
281
+
282
+# Correct: Match the ID type to how the tool was connected
283
+user_personal_tools = composio.tools.get(
284
+ user_id="user_123", # Individual user ID
285
+ toolkits=["gmail"] # User's personal Gmail
286
+)
287
+
288
+org_shared_tools = composio.tools.get(
289
+ user_id="org_123", # Organization ID
290
+ toolkits=["slack", "jira"] # Organization's shared tools
291
+)
292
+```
293
+ </Tab>
294
+ <Tab value="TypeScript">
295
+```typescript
296
+// Wrong: Using individual user ID for org-connected tool
297
+const userTools = await composio.tools.get(req.user.id, {
298
+ toolkits: ['slack'], // Fails - Slack is connected at org level
299
+});
300
+
301
+// Correct: Match the ID type to how the tool was connected
302
+const userPersonalTools = await composio.tools.get(req.user.id, {
303
+ toolkits: ['gmail'], // User's personal Gmail
304
+});
305
+
306
+const orgSharedTools = await composio.tools.get(req.user.organizationId, {
307
+ toolkits: ['slack', 'jira'], // Organization's shared tools
308
+});
309
+```
310
+ </Tab>
311
+</Tabs>
312
+
313
+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.
314
+
315
+## Best Practices
316
+
317
+**Your responsibilities:**
318
+- Pass the correct User ID for each user
319
+- Verify user permissions before executing organization tools
320
+- Never use 'default' in production with multiple users
321
+- Keep User IDs consistent across your application and Composio
322
+- Use stable identifiers that won't change over time
323
+
324
+**Data isolation:** Composio ensures complete isolation between User IDs. Users cannot access another ID's connections or data.