Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
user and session
Sushmithamallesh committed
Nov 29, 2025 at 23:04 UTC
75af14185e13e4701beb8934bf2b7a61b67c2d1b
6 files changed
+438
-19
fern/docs.yml
+3
@@ -329,6 +329,9 @@ navigation:
329
- page: Using as Native Tools
330
path: pages/dist/tool-router/using-as-native-tools.mdx
331
slug: using-as-native-tools
332
+ - page: Handling Files
333
+ path: pages/dist/tool-router/file-upload-download.mdx
334
+ slug: file-upload-download
335
- tab: providers
336
layout:
337
- section: Supported Providers
fern/pages/src/tool-router/creating-sessions.mdx
+338
-3
@@ -1,7 +1,342 @@
1
---
2
-title: Creating Sessions
2
+title: Creating sessions
3
image: "https://og.composio.dev/api/og?title=Creating%20Sessions"
4
-description: "Create and manage sessions for users"
5
-keywords: "tool router"
4
+description: "Configure toolkits, authentication, and connections for a session"
5
+keywords: "sessions, create session, tool router, configuration"
6
+hide-nav-links: false
7
---
8
9
+Create a session to configure what tools are available and how authentication works for a user.
10
+
11
+## Basic session
12
+
13
+Create a session with all available toolkits:
14
+
15
+<CodeGroup>
16
+```python Python
17
+from composio import Composio
18
+
19
+composio = Composio(api_key="your-api-key")
20
+session = composio.create(user_id="pg-user-550e8400-e29b-41d4")
21
+```
22
+
23
+```typescript TypeScript
24
+import { Composio } from "@composio/core";
25
+
26
+const composio = new Composio({ apiKey: "your-api-key" });
27
+const session = await composio.create("pg-user-550e8400-e29b-41d4");
28
+```
29
+</CodeGroup>
30
+
31
+## Configuration options
32
+
33
+### toolkits
34
+
35
+Restrict which toolkits are available in the session.
36
+
37
+**Enable specific toolkits:**
38
+
39
+<CodeGroup>
40
+```python Python
41
+session = composio.create(
42
+ user_id="pg-user-550e8400-e29b-41d4",
43
+ toolkits=["github", "gmail", "slack"]
44
+)
45
+```
46
+
47
+```typescript TypeScript
48
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
49
+ toolkits: ["github", "gmail", "slack"],
50
+});
51
+```
52
+</CodeGroup>
53
+
54
+**Disable specific toolkits:**
55
+
56
+<CodeGroup>
57
+```python Python
58
+session = composio.create(
59
+ user_id="pg-user-550e8400-e29b-41d4",
60
+ toolkits={"disable": ["exa", "firecrawl"]}
61
+)
62
+```
63
+
64
+```typescript TypeScript
65
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
66
+ toolkits: { disable: ["exa", "firecrawl"] },
67
+});
68
+```
69
+</CodeGroup>
70
+
71
+### authConfigs
72
+
73
+Override which auth configs to use for specific toolkits. Use this to:
74
+- Use your own OAuth credentials ([white-labeling](/tool-router/white-labeling-authentication))
75
+- Control which auth config Tool Router uses instead of auto-creating one
76
+
77
+<CodeGroup>
78
+```python Python
79
+session = composio.create(
80
+ user_id="pg-user-550e8400-e29b-41d4",
81
+ auth_configs={
82
+ "github": "ac_your_github_config",
83
+ "slack": "ac_your_slack_config"
84
+ }
85
+)
86
+```
87
+
88
+```typescript TypeScript
89
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
90
+ authConfigs: {
91
+ github: "ac_your_github_config",
92
+ slack: "ac_your_slack_config",
93
+ },
94
+});
95
+```
96
+</CodeGroup>
97
+
98
+When an auth config override is provided, Tool Router uses it to find or create a connected account for the user on that config.
99
+
100
+### connectedAccounts
101
+
102
+Specify which connected account to use for a toolkit. Use this when:
103
+- A user has multiple accounts for the same toolkit (e.g., personal and work Gmail)
104
+- You need deterministic account selection instead of "most recent"
105
+
106
+<CodeGroup>
107
+```python Python
108
+session = composio.create(
109
+ user_id="pg-user-550e8400-e29b-41d4",
110
+ connected_accounts={
111
+ "gmail": "ca_work_gmail",
112
+ "github": "ca_personal_github"
113
+ }
114
+)
115
+```
116
+
117
+```typescript TypeScript
118
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
119
+ connectedAccounts: {
120
+ gmail: "ca_work_gmail",
121
+ github: "ca_personal_github",
122
+ },
123
+});
124
+```
125
+</CodeGroup>
126
+
127
+This takes highest precedence when selecting which account to use for tool execution. See [connected account precedence](/tool-router/users-and-sessions#connected-account-precedence).
128
+
129
+### manageConnections
130
+
131
+Controls whether the `COMPOSIO_MANAGE_CONNECTIONS` meta-tool is included in the session. This tool allows the agent to prompt users to connect accounts during chat.
132
+
133
+- `true` (default) - Agent can prompt users to connect accounts via auth links
134
+- `false` - Tool not included. Use `session.authorize()` for manual auth
135
+- `{ callbackUrl: "..." }` - Agent can prompt users, redirects to your URL after OAuth
136
+
137
+**Disable in-chat authentication:**
138
+
139
+<CodeGroup>
140
+```python Python
141
+session = composio.create(
142
+ user_id="pg-user-550e8400-e29b-41d4",
143
+ manage_connections=False
144
+)
145
+```
146
+
147
+```typescript TypeScript
148
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
149
+ manageConnections: false,
150
+});
151
+```
152
+</CodeGroup>
153
+
154
+**Custom callback URL:**
155
+
156
+<CodeGroup>
157
+```python Python
158
+session = composio.create(
159
+ user_id="pg-user-550e8400-e29b-41d4",
160
+ manage_connections={"callback_url": "https://myapp.com/callback"}
161
+)
162
+```
163
+
164
+```typescript TypeScript
165
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
166
+ manageConnections: { callbackUrl: "https://myapp.com/callback" },
167
+});
168
+```
169
+</CodeGroup>
170
+
171
+For more details, see [Using in-chat authentication](/tool-router/using-in-chat-authentication) and [Manually authenticating users](/tool-router/manually-authenticating-users).
172
+
173
+## Full example
174
+
175
+<CodeGroup>
176
+```python Python
177
+from composio import Composio
178
+from composio_openai_agents import OpenAIAgentsProvider
179
+
180
+composio = Composio(
181
+ api_key="your-api-key",
182
+ provider=OpenAIAgentsProvider()
183
+)
184
+
185
+session = composio.create(
186
+ user_id="pg-user-550e8400-e29b-41d4",
187
+ toolkits=["github", "gmail", "slack"],
188
+ auth_configs={
189
+ "github": "ac_your_github_config"
190
+ },
191
+ connected_accounts={
192
+ "gmail": "ca_work_gmail"
193
+ },
194
+ manage_connections={"callback_url": "https://myapp.com/callback"}
195
+)
196
+```
197
+
198
+```typescript TypeScript
199
+import { Composio } from "@composio/core";
200
+import { OpenAIAgentsProvider } from "@composio/openai-agents";
201
+
202
+const composio = new Composio({
203
+ apiKey: "your-api-key",
204
+ provider: new OpenAIAgentsProvider(),
205
+});
206
+
207
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
208
+ toolkits: ["github", "gmail", "slack"],
209
+ authConfigs: {
210
+ github: "ac_your_github_config",
211
+ },
212
+ connectedAccounts: {
213
+ gmail: "ca_work_gmail",
214
+ },
215
+ manageConnections: { callbackUrl: "https://myapp.com/callback" },
216
+});
217
+```
218
+</CodeGroup>
219
+
220
+## Session properties
221
+
222
+### tools()
223
+
224
+Get meta-tools to pass to your agent framework.
225
+
226
+<CodeGroup>
227
+```python Python
228
+tools = session.tools()
229
+
230
+agent = Agent(
231
+ name="Assistant",
232
+ instructions="You are a helpful assistant.",
233
+ tools=tools
234
+)
235
+```
236
+
237
+```typescript TypeScript
238
+const tools = await session.tools();
239
+
240
+const agent = new Agent({
241
+ name: "Assistant",
242
+ instructions: "You are a helpful assistant.",
243
+ tools: tools,
244
+});
245
+```
246
+</CodeGroup>
247
+
248
+For framework-specific examples, see [Using as native tools](/tool-router/using-as-native-tools).
249
+
250
+### mcp
251
+
252
+Get the MCP server URL to use with any MCP-compatible client.
253
+
254
+<CodeGroup>
255
+```python Python
256
+mcp_url = session.mcp.url
257
+```
258
+
259
+```typescript TypeScript
260
+const { mcp } = session;
261
+console.log(mcp.url);
262
+```
263
+</CodeGroup>
264
+
265
+Example with OpenAI Agents SDK:
266
+
267
+```typescript
268
+import { Agent } from "@openai/agents";
269
+
270
+const agent = new Agent({
271
+ name: "Assistant",
272
+ instructions: "You are a helpful assistant.",
273
+ tools: [
274
+ hostedMcpTool({
275
+ serverLabel: "composio",
276
+ serverUrl: mcp.url,
277
+ }),
278
+ ],
279
+});
280
+```
281
+
282
+For more frameworks, see [Using with MCP clients](/tool-router/using-with-mcp-clients).
283
+
284
+### authorize()
285
+
286
+Manually authenticate a user to a toolkit outside of the chat flow. See [Manually authenticating users](/tool-router/manually-authenticating-users).
287
+
288
+<CodeGroup>
289
+```python Python
290
+connection_request = session.authorize(
291
+ "github",
292
+ callback_url="https://myapp.com/callback"
293
+)
294
+
295
+print(connection_request.redirect_url)
296
+
297
+connected_account = connection_request.wait_for_connection()
298
+```
299
+
300
+```typescript TypeScript
301
+const connectionRequest = await session.authorize("github", {
302
+ callbackUrl: "https://myapp.com/callback",
303
+});
304
+
305
+console.log(connectionRequest.redirectUrl);
306
+
307
+const connectedAccount = await connectionRequest.waitForConnection();
308
+```
309
+</CodeGroup>
310
+
311
+### toolkits()
312
+
313
+List available toolkits and their connection status for the session. Use this to build a UI showing which apps are connected.
314
+
315
+<CodeGroup>
316
+```python Python
317
+toolkits = session.toolkits(
318
+ order_by="popularity",
319
+ is_connected=True
320
+)
321
+
322
+for toolkit in toolkits:
323
+ print(f"{toolkit.name}: {toolkit.connected_account.id if toolkit.connected_account else 'Not connected'}")
324
+```
325
+
326
+```typescript TypeScript
327
+const toolkits = await session.toolkits({
328
+ orderBy: "popularity",
329
+ isConnected: true,
330
+});
331
+
332
+toolkits.forEach((toolkit) => {
333
+ console.log(`${toolkit.name}: ${toolkit.connectedAccount?.id ?? "Not connected"}`);
334
+});
335
+```
336
+</CodeGroup>
337
+
338
+**Filter options:**
339
+- `orderBy`: `"popularity"`, `"name"`, or `"connected_at"`
340
+- `isConnected`: `true` to show only connected toolkits
341
+- `category`: Filter by category (e.g., `"productivity"`, `"communication"`)
342
+
fern/pages/src/tool-router/file-upload-download.mdx
new
+9
@@ -0,0 +1,9 @@
1
+---
2
+title: Handling files
3
+image: "https://og.composio.dev/api/og?title=Handling%20Files"
4
+description: "Handle file uploads and downloads with Tool Router"
5
+keywords: "file upload, file download, tool router"
6
+hide-nav-links: false
7
+---
8
+
9
+Coming soon.
fern/pages/src/tool-router/overview.mdx
+2
-2
@@ -23,7 +23,7 @@ To use Tool Router, create a session for a user:
23
<CodeGroup>
24
```python Python
25
session = composio.create(
26
- user_id='user_id_123',
26
+ user_id='pg-user-550e8400-e29b-41d4',
27
toolkits=['github', 'slack', 'gmail']
28
)
29
@@ -35,7 +35,7 @@ session = composio.create(
35
```
36
37
```typescript TypeScript
38
-const { tools, mcp, authorize, toolkits } = await composio.create('user_id_123', {
38
+const { tools, mcp, authorize, toolkits } = await composio.create('pg-user-550e8400-e29b-41d4', {
39
toolkits: ['github', 'slack', 'gmail'],
40
});
41
fern/pages/src/tool-router/quickstart.mdx
+10
-10
@@ -23,7 +23,7 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us
23
24
<Info>
25
`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).
26
-`user_123`: The [ID of the user](/docs/user-management) in your system.
26
+`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.
27
</Info>
28
```python
29
from composio import Composio
@@ -35,7 +35,7 @@ composio = Composio(
35
)
36
37
# Create a session for a user
38
-session = composio.create(user_id="user_123")
38
+session = composio.create(user_id="pg-user-550e8400-e29b-41d4")
39
```
40
</Step>
41
@@ -77,7 +77,7 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us
77
78
<Info>
79
`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).
80
-`user_123`: The [ID of the user](/docs/user-management) in your system.
80
+`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.
81
</Info>
82
```typescript
83
import { Composio } from "@composio/core";
@@ -89,7 +89,7 @@ const composio = new Composio({
89
});
90
91
// Create a session for a user
92
-const { tools } = await composio.create("user_123");
92
+const { tools } = await composio.create("pg-user-550e8400-e29b-41d4");
93
```
94
</Step>
95
@@ -131,7 +131,7 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us
131
132
<Info>
133
`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).
134
-`user_123`: The [ID of the user](/docs/user-management) in your system.
134
+`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.
135
</Info>
136
```python
137
from composio import Composio
@@ -143,7 +143,7 @@ composio = Composio(
143
)
144
145
# Create a session for a user
146
-session = composio.create(user_id="user_123")
146
+session = composio.create(user_id="pg-user-550e8400-e29b-41d4")
147
```
148
</Step>
149
@@ -185,7 +185,7 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us
185
186
<Info>
187
`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).
188
-`user_123`: The [ID of the user](/docs/user-management) in your system.
188
+`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.
189
</Info>
190
```typescript
191
import { Composio } from "@composio/core";
@@ -197,7 +197,7 @@ const composio = new Composio({
197
});
198
199
// Create a session for a user
200
-const { mcp } = await composio.create("user_123");
200
+const { mcp } = await composio.create("pg-user-550e8400-e29b-41d4");
201
```
202
</Step>
203
@@ -239,7 +239,7 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us
239
240
<Info>
241
`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).
242
-`user_123`: The [ID of the user](/docs/user-management) in your system.
242
+`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.
243
</Info>
244
```typescript
245
import { Composio } from "@composio/core";
@@ -251,7 +251,7 @@ const composio = new Composio({
251
});
252
253
// Create a session for a user
254
-const { tools } = await composio.create("user_123");
254
+const { tools } = await composio.create("pg-user-550e8400-e29b-41d4");
255
```
256
</Step>
257
fern/pages/src/tool-router/users-and-sessions.mdx
+76
-4
@@ -1,8 +1,80 @@
1
---
2
-title: Users and Sessions
2
+title: Users and sessions
3
image: "https://og.composio.dev/api/og?title=Users%20and%20Sessions"
4
-description: ""
5
-keywords: ""
6
-subtitle: ""
4
+description: "Understand how Tool Router scopes tools and connections per user"
5
+keywords: "sessions, users, tool router, configuration"
6
hide-nav-links: false
7
---
8
+
9
+Sessions are ephemeral, user-scoped configurations that define what tools are available and how authentication works.
10
+
11
+## Users
12
+
13
+A user ID is an identifier from your system (database UUID, primary key) that Composio uses to scope connected accounts and tool access.
14
+
15
+<CodeGroup>
16
+```python Python
17
+session = composio.create(user_id="pg-user-550e8400-e29b-41d4")
18
+```
19
+
20
+```typescript TypeScript
21
+const session = await composio.create("pg-user-550e8400-e29b-41d4");
22
+```
23
+</CodeGroup>
24
+
25
+User IDs can represent individuals, teams, or organizations depending on your application. For detailed patterns, see [User Management](/docs/user-management).
26
+
27
+## Sessions
28
+
29
+A session defines the execution context for Tool Router's meta-tools. It combines:
30
+- Which user's connected accounts to use
31
+- Which toolkits are available
32
+- Which auth configs to use
33
+
34
+Tool Router's meta-tools (search, execute, workbench, manage connections) are the same for everyone. The session determines the context they operate within - when the agent searches for tools, it searches within the session's allowed toolkits. When it executes a tool, it uses the session user's connected accounts.
35
+
36
+### Creating a session
37
+
38
+A session pulls together your user's auth state with your toolkit configuration. All options are optional - by default, all toolkits with Composio managed auth are enabled.
39
+
40
+<CodeGroup>
41
+```python Python
42
+session = composio.create(
43
+ user_id="pg-user-550e8400-e29b-41d4",
44
+ toolkits=["github", "gmail", "slack"],
45
+ auth_configs={
46
+ "github": "ac_your_github_config"
47
+ }
48
+)
49
+```
50
+
51
+```typescript TypeScript
52
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
53
+ toolkits: ["github", "gmail", "slack"],
54
+ authConfigs: {
55
+ github: "ac_your_github_config",
56
+ },
57
+});
58
+```
59
+</CodeGroup>
60
+
61
+For all configuration options, see [Creating sessions](/tool-router/creating-sessions).
62
+
63
+### Connections persist
64
+
65
+Connected accounts are stored in Composio and persist across sessions. When a user connects their GitHub account in one session, it remains available in future sessions.
66
+
67
+Sessions configure *which* connections to use, but don't own the connections themselves.
68
+
69
+## Connected account precedence
70
+
71
+When executing a tool, Tool Router selects the connected account in this order:
72
+
73
+1. `connectedAccounts` override if provided in session config
74
+2. `authConfigs` override - finds or creates connection on that config
75
+3. Auth config previously created by Tool Router for this toolkit
76
+4. Creates new auth config using Composio managed auth (tagged as Tool Router created)
77
+5. Error if no Composio managed auth scheme exists for the toolkit
78
+
79
+If a user has multiple connected accounts for a toolkit, the most recently connected one is used.
80
+