@devries-cameron20 / composio-1 / commits / 55b823a1b
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

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