@devries-cameron20 / composio-1 / commits / 75af14185
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.

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 +