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, 20:45 UTC
Adding User management page in docs (#1930)
Co-authored-by: Musthaq Ahamad <53584487+haxzie@users.noreply.github.com>
Sushmitha Mallesh committed
Sep 15, 2025 at 14:55 UTC
55b823a1b8d0f725fe6310722c891685bf652370
5 files changed
+327
-3
fern/docs.yml
+3
@@ -153,6 +153,9 @@ navigation:
153
- page: Custom Auth Parameters
154
path: pages/dist/authentication/custom-auth-params.mdx
155
slug: custom-auth-params
156
+ - page: User Management
157
+ path: pages/dist/authentication/user-management.mdx
158
+ slug: user-management
159
- section: Triggers
160
icon: bolt
161
skip-slug: true
fern/pages/src/authentication/user-management.mdx
new
+315
@@ -0,0 +1,315 @@
1
+---
2
+title: "User Management"
3
+keywords: "user management, user Id, user context, external user ID"
4
+subtitle: "Learn how to manage users for your application"
5
+hide-nav-links: false
6
+---
7
+
8
+## What are User IDs?
9
+User IDs determine whose connected accounts and data you're accessing in Composio. Every tool execution, connection authorization, and account operation
10
+requires a `userId` parameter that identifies which context to use.
11
+
12
+User IDs act as containers that group connected accounts together across toolkits. Depending on your application, you can use User IDs to represent an
13
+individual user, a team, or an entire organization.
14
+
15
+## Quick Decision Guide
16
+
17
+**How do users access connected accounts in your app?**
18
+
19
+- **Each user connects their own personal accounts?**
20
+Use User IDs
21
+*Use your database UUID or primary key (e.g., `user.id`)*
22
+*Example: Users connect their personal Gmail, GitHub*
23
+
24
+- **Teams share the same connected accounts?**
25
+Use Organization IDs
26
+*Use your organization UUID or primary key (e.g., `organization.id`)*
27
+*Example: Company Slack workspace*
28
+
29
+## Patterns
30
+
31
+### User IDs (Individual Accounts)
32
+
33
+In production applications with multiple users, where each user connects and manages their own accounts.
34
+
35
+**Choosing User IDs:**
36
+
37
+- Recommended: Database UUID or primary key (`user.id`)
38
+- Acceptable: Unique username (`user.username`)
39
+- Avoid: Email addresses (emails can change)
40
+
41
+<CodeGroup>
42
+```typescript Typescript
43
+// Use your database's user ID (UUID, primary key, etc.)
44
+const userId = user.id; // e.g., "550e8400-e29b-41d4-a716-446655440000"
45
+
46
+const tools = await composio.tools.get(userId, {
47
+ toolkits: ['github'],
48
+});
49
+
50
+const result = await composio.tools.execute('GITHUB_GET_REPO', {
51
+ userId: userId,
52
+ arguments: { owner: 'example', repo: 'repo' },
53
+});
54
+```
55
+
56
+```python Python
57
+# Use your database's user ID (UUID, primary key, etc.)
58
+user_id = user.id; # e.g., "550e8400-e29b-41d4-a716-446655440000"
59
+
60
+tools = composio.tools.get(
61
+ user_id=user_id,
62
+ toolkits=["GITHUB"],
63
+)
64
+
65
+result = composio.tools.execute(
66
+ "GITHUB_GET_REPO",
67
+ user_id=user_id,
68
+ arguments={
69
+ "owner": 'example',
70
+ "repo": 'repo'
71
+ }
72
+)
73
+```
74
+
75
+</CodeGroup>
76
+<Warning>
77
+Never use 'default' as an User ID in production with users. This could expose other users' data
78
+</Warning>
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(at)company.com, company GitHub org
87
+- Enterprise apps: IT manages connections for all employees
88
+
89
+<CodeGroup>
90
+```typescript TypeScript
91
+// Use the organization ID as userId
92
+const userId = organization.id; // e.g., "org_550e8400"
93
+
94
+// All users in the organization share the same connected accounts
95
+const tools = await composio.tools.get(userId, {
96
+ toolkits: ['slack'],
97
+});
98
+
99
+// Execute tools in the organization context
100
+const result = await composio.tools.execute('SLACK_SEND_MESSAGE', {
101
+ userId: userId,
102
+ arguments: {
103
+ channel: '#general',
104
+ text: 'Hello from the team!',
105
+ },
106
+});
107
+```
108
+```python Python
109
+# Use the organization ID as userId
110
+user_id = organization.id # e.g., "org_550e8400"
111
+
112
+# All users in the organization share the same connected accounts
113
+tools = composio.tools.get(
114
+ user_id=user_id,
115
+ toolkits=["SLACK"],
116
+)
117
+
118
+# Execute tools in the organization context
119
+result = composio.tools.execute(
120
+ "SLACK_SEND_MESSAGE",
121
+ user_id=user_id,
122
+ arguments={
123
+ "channel": '#general',
124
+ "text": 'Hello from the team!'
125
+ }
126
+)
127
+```
128
+</CodeGroup>
129
+
130
+## Multiple Connected Accounts
131
+
132
+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.
133
+
134
+**Key concepts:**
135
+- Each connected account gets a unique Connected Account ID
136
+- Multiple accounts can exist under the same User ID for any toolkit
137
+- You can specify which account to use when executing tools
138
+
139
+**Account selection:**
140
+- **Explicit:** Specify the Connected Account ID to target a specific account
141
+- **Default:** If no Connected Account ID is provided, the most recently connected account is used
142
+
143
+## Examples
144
+### Organization-Based Application
145
+
146
+In B2B applications, typically an admin connects accounts once and all team members share access. Here's a complete implementation:
147
+
148
+**Key concepts:**
149
+- Admin performs the OAuth connection using organization ID
150
+- All team members execute tools using the same organization ID
151
+- Permission checks ensure users can only access their organization's connections
152
+```typescript TypeScript
153
+import { Composio } from '@composio/core';
154
+const composio = new Composio({
155
+ apiKey: process.env.COMPOSIO_API_KEY,
156
+});
157
+
158
+// 1. Admin connects Slack for the entire organization
159
+async function connectOrganizationToSlack(organizationId: string, adminUserId: string) {
160
+ // Use organization ID as userId in Composio
161
+ const connectionRequest = await composio.toolkits.authorize(organizationId, 'slack');
162
+
163
+ // Store the connection request for the admin to complete
164
+ await storeConnectionRequest(organizationId, adminUserId, connectionRequest);
165
+
166
+ return connectionRequest.redirectUrl;
167
+}
168
+
169
+// 2. Any user in the organization can use the connected tools
170
+async function sendSlackMessage(organizationId: string, channel: string, message: string) {
171
+ return await composio.tools.execute('SLACK_SEND_MESSAGE', {
172
+ userId: organizationId, // organization ID, not individual user ID
173
+ arguments: {
174
+ channel: channel,
175
+ text: message,
176
+ },
177
+ });
178
+}
179
+
180
+// 3. Check if organization has required connections
181
+async function getOrganizationTools(organizationId: string) {
182
+ return await composio.tools.get(organizationId, {
183
+ toolkits: ['slack', 'github', 'jira'],
184
+ });
185
+}
186
+
187
+// Usage in your API endpoint
188
+app.post('/api/slack/message', async (req, res) => {
189
+ const { channel, message } = req.body;
190
+ const organizationId = req.user.organizationId; // Get from your auth system
191
+
192
+ // Verify user has permission to send messages for this organization
193
+ // The userCanSendMessages function is your responsibility - implement it based on your application's permission model (role-based, feature flags, etc.).
194
+ if (!(await userCanSendMessages(req.user.id, organizationId))) {
195
+ return res.status(403).json({ error: 'Insufficient permissions' });
196
+ }
197
+
198
+ try {
199
+ const result = await sendSlackMessage(organizationId, channel, message);
200
+ res.json(result.data);
201
+ } catch (error) {
202
+ res.status(500).json({ error: 'Failed to send message' });
203
+ }
204
+});
205
+```
206
+
207
+
208
+### Multi-User Application
209
+
210
+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.
211
+
212
+**Key concepts:**
213
+- Each user authorizes their own accounts using their unique user ID
214
+- Connections are isolated - users can only access their own connected accounts
215
+- No permission checks needed since users only access their own data
216
+
217
+```typescript TypeScript
218
+import { Composio } from '@composio/core';
219
+const composio = new Composio({
220
+ apiKey: process.env.COMPOSIO_API_KEY,
221
+});
222
+
223
+// 1. User initiates GitHub connection
224
+async function connectUserToGitHub(userId: string) {
225
+ const connectionRequest = await composio.toolkits.authorize(userId, 'github');
226
+ return connectionRequest.redirectUrl;
227
+}
228
+
229
+// 2. Get user's connected GitHub tools
230
+async function getUserGitHubTools(userId: string) {
231
+ return await composio.tools.get(userId, {
232
+ toolkits: ['github'],
233
+ });
234
+}
235
+
236
+// 3. Execute tool for specific user
237
+async function getUserRepos(userId: string) {
238
+ return await composio.tools.execute('GITHUB_LIST_REPOS', {
239
+ userId: userId,
240
+ arguments: {
241
+ per_page: 10,
242
+ },
243
+ });
244
+}
245
+
246
+// Usage in your API endpoint
247
+app.get('/api/github/repos', async (req, res) => {
248
+ const userId = req.user.id; // Get from your auth system
249
+
250
+ try {
251
+ const repos = await getUserRepos(userId);
252
+ res.json(repos.data);
253
+ } catch (error) {
254
+ res.status(500).json({ error: 'Failed to fetch repos' });
255
+ }
256
+});
257
+```
258
+
259
+**Data isolation**: Composio ensures each userId's connections and data are completely separate. User A can never access User B's repositories.
260
+
261
+### Hybrid Pattern
262
+
263
+Many applications need both personal and team resources. Users might connect their personal Gmail while sharing the company Slack workspace.
264
+
265
+**Common scenarios:**
266
+- Personal calendars + shared project management
267
+- Individual GitHub accounts + organization repositories
268
+
269
+<CodeGroup>
270
+```typescript TypeScript
271
+// ❌ Wrong: Using individual user ID for org-connected tool
272
+const userTools = await composio.tools.get(req.user.id, {
273
+ toolkits: ['slack'], // Fails - Slack is connected at org level
274
+});
275
+
276
+// ✅ Correct: Match the ID type to how the tool was connected
277
+const userPersonalTools = await composio.tools.get(req.user.id, {
278
+ toolkits: ['gmail'], // User's personal Gmail
279
+});
280
+
281
+const orgSharedTools = await composio.tools.get(req.user.organizationId, {
282
+ toolkits: ['slack', 'jira'], // Organization's shared tools
283
+});
284
+```
285
+```python Python
286
+# ❌ Wrong: Using individual user ID for org-connected tool
287
+user_tools = composio.tools.get(
288
+ user_id="user_123", # Individual user ID
289
+ toolkits=["slack"] # Fails - Slack is connected at org level
290
+)
291
+
292
+# ✅ Correct: Match the ID type to how the tool was connected
293
+user_personal_tools = composio.tools.get(
294
+ user_id="user_123", # Individual user ID
295
+ toolkits=["gmail"] # User's personal Gmail
296
+)
297
+
298
+org_shared_tools = composio.tools.get(
299
+ user_id="org_123", # Organization ID
300
+ toolkits=["slack", "jira"] # Organization's shared tools
301
+)
302
+```
303
+</CodeGroup>
304
+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.
305
+
306
+## Best Practices
307
+
308
+**Your responsibilities:**
309
+- Pass the correct User ID for each user
310
+- Verify user permissions before executing organization tools
311
+- Never use 'default' in production with multiple users
312
+- Keep User IDs consistent across your application and Composio
313
+- Use stable identifiers that won't change over time
314
+
315
+**Data isolation:** Composio ensures complete isolation between User IDs. Users cannot access another ID's connections or data.
\ No newline at end of file
fern/pages/src/tool-calling/authenticating-tools.mdx
+6
@@ -75,6 +75,12 @@ With an auth config created, you're ready to authenticate your users!
75
76
You can either use [**Connect Link**](#hosted-authentication-connect-link) for a hosted authentication flow, or use [**Direct SDK Integration**](#direct-sdk-integration).
77
78
+<Note>
79
+User authentication requires a User ID - a unique identifier that groups connected accounts together. Learn more about [User Management](/docs/user-management) to understand how to structure User IDs for your application.
80
+</Note>
81
+
82
+**Choose the section below that matches your toolkit's authentication method:**
83
+
84
### Hosted Authentication (Connect Link)
85
86
Redirect users to a Composio-hosted URL that handles the entire authentication process—OAuth flows, API key collection, or custom fields like subdomain. You can specify a callback URL to control where users return after authentication.
fern/pages/src/tool-calling/executing-tools.mdx
+1
-2
@@ -12,8 +12,7 @@ In Composio, every **tool** is a single API action—fully described with schema
12
13
<Tip icon="info">
14
**User Scoping**: All tools are scoped to a specific user - that's why every example includes a
15
- `user_id`. Each user must authenticate with their respective services (Gmail, Calendar, etc.)
16
- before executing tools. [Learn more about authentication →](./authenticating-tools)
15
+ `user_id`. Learn how to structure User IDs in [User Management](./user-management). Each user must authenticate with their respective services (Gmail, Calendar, etc.) - see [Authentication](./authenticating-tools)
16
</Tip>
17
18
## Using Chat Completions
fern/pages/src/triggers/using-triggers.mdx
+2
-1
@@ -17,7 +17,8 @@ Each event is delivered as a **structured payload** to your webhook endpoint (vi
17
<Tip title="Prerequisites">
18
Before proceeding, ensure you've created an [auth
19
config](/docs/authenticating-tools#creating-an-auth-config) and [established a
20
- connection](/docs/authenticating-tools#oauth-connections) to an app (e.g., Slack, GitHub).
20
+ connection](/docs/authenticating-tools#oauth-connections) to an app (e.g., Slack, GitHub).
21
+ Triggers are scoped to specific users - learn about [User Management](/docs/user-management) for guidance on structuring User IDs.
22
</Tip>
23
24
## Creating a trigger