Skip to content

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

Sushmithamallesh75af14185e13
diff --git a/fern/docs.yml b/fern/docs.yml
index e30358815..2900e5c77 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -329,6 +329,9 @@ navigation:
- page: Using as Native Tools
path: pages/dist/tool-router/using-as-native-tools.mdx
slug: using-as-native-tools
+ - page: Handling Files
+ path: pages/dist/tool-router/file-upload-download.mdx
+ slug: file-upload-download
- tab: providers
layout:
- section: Supported Providers
diff --git a/fern/pages/src/tool-router/creating-sessions.mdx b/fern/pages/src/tool-router/creating-sessions.mdx
index 3c0141ac3..d8db37091 100644
--- a/fern/pages/src/tool-router/creating-sessions.mdx
+++ b/fern/pages/src/tool-router/creating-sessions.mdx
@@ -1,7 +1,342 @@
---
-title: Creating Sessions
+title: Creating sessions
image: "https://og.composio.dev/api/og?title=Creating%20Sessions"
-description: "Create and manage sessions for users"
-keywords: "tool router"
+description: "Configure toolkits, authentication, and connections for a session"
+keywords: "sessions, create session, tool router, configuration"
+hide-nav-links: false
---
+Create a session to configure what tools are available and how authentication works for a user.
+
+## Basic session
+
+Create a session with all available toolkits:
+
+<CodeGroup>
+```python Python
+from composio import Composio
+
+composio = Composio(api_key="your-api-key")
+session = composio.create(user_id="pg-user-550e8400-e29b-41d4")
+```
+
+```typescript TypeScript
+import { Composio } from "@composio/core";
+
+const composio = new Composio({ apiKey: "your-api-key" });
+const session = await composio.create("pg-user-550e8400-e29b-41d4");
+```
+</CodeGroup>
+
+## Configuration options
+
+### toolkits
+
+Restrict which toolkits are available in the session.
+
+**Enable specific toolkits:**
+
+<CodeGroup>
+```python Python
+session = composio.create(
+ user_id="pg-user-550e8400-e29b-41d4",
+ toolkits=["github", "gmail", "slack"]
+)
+```
+
+```typescript TypeScript
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
+ toolkits: ["github", "gmail", "slack"],
+});
+```
+</CodeGroup>
+
+**Disable specific toolkits:**
+
+<CodeGroup>
+```python Python
+session = composio.create(
+ user_id="pg-user-550e8400-e29b-41d4",
+ toolkits={"disable": ["exa", "firecrawl"]}
+)
+```
+
+```typescript TypeScript
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
+ toolkits: { disable: ["exa", "firecrawl"] },
+});
+```
+</CodeGroup>
+
+### authConfigs
+
+Override which auth configs to use for specific toolkits. Use this to:
+- Use your own OAuth credentials ([white-labeling](/tool-router/white-labeling-authentication))
+- Control which auth config Tool Router uses instead of auto-creating one
+
+<CodeGroup>
+```python Python
+session = composio.create(
+ user_id="pg-user-550e8400-e29b-41d4",
+ auth_configs={
+ "github": "ac_your_github_config",
+ "slack": "ac_your_slack_config"
+ }
+)
+```
+
+```typescript TypeScript
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
+ authConfigs: {
+ github: "ac_your_github_config",
+ slack: "ac_your_slack_config",
+ },
+});
+```
+</CodeGroup>
+
+When an auth config override is provided, Tool Router uses it to find or create a connected account for the user on that config.
+
+### connectedAccounts
+
+Specify which connected account to use for a toolkit. Use this when:
+- A user has multiple accounts for the same toolkit (e.g., personal and work Gmail)
+- You need deterministic account selection instead of "most recent"
+
+<CodeGroup>
+```python Python
+session = composio.create(
+ user_id="pg-user-550e8400-e29b-41d4",
+ connected_accounts={
+ "gmail": "ca_work_gmail",
+ "github": "ca_personal_github"
+ }
+)
+```
+
+```typescript TypeScript
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
+ connectedAccounts: {
+ gmail: "ca_work_gmail",
+ github: "ca_personal_github",
+ },
+});
+```
+</CodeGroup>
+
+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).
+
+### manageConnections
+
+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.
+
+- `true` (default) - Agent can prompt users to connect accounts via auth links
+- `false` - Tool not included. Use `session.authorize()` for manual auth
+- `{ callbackUrl: "..." }` - Agent can prompt users, redirects to your URL after OAuth
+
+**Disable in-chat authentication:**
+
+<CodeGroup>
+```python Python
+session = composio.create(
+ user_id="pg-user-550e8400-e29b-41d4",
+ manage_connections=False
+)
+```
+
+```typescript TypeScript
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
+ manageConnections: false,
+});
+```
+</CodeGroup>
+
+**Custom callback URL:**
+
+<CodeGroup>
+```python Python
+session = composio.create(
+ user_id="pg-user-550e8400-e29b-41d4",
+ manage_connections={"callback_url": "https://myapp.com/callback"}
+)
+```
+
+```typescript TypeScript
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
+ manageConnections: { callbackUrl: "https://myapp.com/callback" },
+});
+```
+</CodeGroup>
+
+For more details, see [Using in-chat authentication](/tool-router/using-in-chat-authentication) and [Manually authenticating users](/tool-router/manually-authenticating-users).
+
+## Full example
+
+<CodeGroup>
+```python Python
+from composio import Composio
+from composio_openai_agents import OpenAIAgentsProvider
+
+composio = Composio(
+ api_key="your-api-key",
+ provider=OpenAIAgentsProvider()
+)
+
+session = composio.create(
+ user_id="pg-user-550e8400-e29b-41d4",
+ toolkits=["github", "gmail", "slack"],
+ auth_configs={
+ "github": "ac_your_github_config"
+ },
+ connected_accounts={
+ "gmail": "ca_work_gmail"
+ },
+ manage_connections={"callback_url": "https://myapp.com/callback"}
+)
+```
+
+```typescript TypeScript
+import { Composio } from "@composio/core";
+import { OpenAIAgentsProvider } from "@composio/openai-agents";
+
+const composio = new Composio({
+ apiKey: "your-api-key",
+ provider: new OpenAIAgentsProvider(),
+});
+
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
+ toolkits: ["github", "gmail", "slack"],
+ authConfigs: {
+ github: "ac_your_github_config",
+ },
+ connectedAccounts: {
+ gmail: "ca_work_gmail",
+ },
+ manageConnections: { callbackUrl: "https://myapp.com/callback" },
+});
+```
+</CodeGroup>
+
+## Session properties
+
+### tools()
+
+Get meta-tools to pass to your agent framework.
+
+<CodeGroup>
+```python Python
+tools = session.tools()
+
+agent = Agent(
+ name="Assistant",
+ instructions="You are a helpful assistant.",
+ tools=tools
+)
+```
+
+```typescript TypeScript
+const tools = await session.tools();
+
+const agent = new Agent({
+ name: "Assistant",
+ instructions: "You are a helpful assistant.",
+ tools: tools,
+});
+```
+</CodeGroup>
+
+For framework-specific examples, see [Using as native tools](/tool-router/using-as-native-tools).
+
+### mcp
+
+Get the MCP server URL to use with any MCP-compatible client.
+
+<CodeGroup>
+```python Python
+mcp_url = session.mcp.url
+```
+
+```typescript TypeScript
+const { mcp } = session;
+console.log(mcp.url);
+```
+</CodeGroup>
+
+Example with OpenAI Agents SDK:
+
+```typescript
+import { Agent } from "@openai/agents";
+
+const agent = new Agent({
+ name: "Assistant",
+ instructions: "You are a helpful assistant.",
+ tools: [
+ hostedMcpTool({
+ serverLabel: "composio",
+ serverUrl: mcp.url,
+ }),
+ ],
+});
+```
+
+For more frameworks, see [Using with MCP clients](/tool-router/using-with-mcp-clients).
+
+### authorize()
+
+Manually authenticate a user to a toolkit outside of the chat flow. See [Manually authenticating users](/tool-router/manually-authenticating-users).
+
+<CodeGroup>
+```python Python
+connection_request = session.authorize(
+ "github",
+ callback_url="https://myapp.com/callback"
+)
+
+print(connection_request.redirect_url)
+
+connected_account = connection_request.wait_for_connection()
+```
+
+```typescript TypeScript
+const connectionRequest = await session.authorize("github", {
+ callbackUrl: "https://myapp.com/callback",
+});
+
+console.log(connectionRequest.redirectUrl);
+
+const connectedAccount = await connectionRequest.waitForConnection();
+```
+</CodeGroup>
+
+### toolkits()
+
+List available toolkits and their connection status for the session. Use this to build a UI showing which apps are connected.
+
+<CodeGroup>
+```python Python
+toolkits = session.toolkits(
+ order_by="popularity",
+ is_connected=True
+)
+
+for toolkit in toolkits:
+ print(f"{toolkit.name}: {toolkit.connected_account.id if toolkit.connected_account else 'Not connected'}")
+```
+
+```typescript TypeScript
+const toolkits = await session.toolkits({
+ orderBy: "popularity",
+ isConnected: true,
+});
+
+toolkits.forEach((toolkit) => {
+ console.log(`${toolkit.name}: ${toolkit.connectedAccount?.id ?? "Not connected"}`);
+});
+```
+</CodeGroup>
+
+**Filter options:**
+- `orderBy`: `"popularity"`, `"name"`, or `"connected_at"`
+- `isConnected`: `true` to show only connected toolkits
+- `category`: Filter by category (e.g., `"productivity"`, `"communication"`)
+
diff --git a/fern/pages/src/tool-router/file-upload-download.mdx b/fern/pages/src/tool-router/file-upload-download.mdx
new file mode 100644
index 000000000..d9c6079e6
--- /dev/null
+++ b/fern/pages/src/tool-router/file-upload-download.mdx
@@ -0,0 +1,9 @@
+---
+title: Handling files
+image: "https://og.composio.dev/api/og?title=Handling%20Files"
+description: "Handle file uploads and downloads with Tool Router"
+keywords: "file upload, file download, tool router"
+hide-nav-links: false
+---
+
+Coming soon.
diff --git a/fern/pages/src/tool-router/overview.mdx b/fern/pages/src/tool-router/overview.mdx
index ec4d0de04..8074279bb 100644
--- a/fern/pages/src/tool-router/overview.mdx
+++ b/fern/pages/src/tool-router/overview.mdx
@@ -23,7 +23,7 @@ To use Tool Router, create a session for a user:
<CodeGroup>
```python Python
session = composio.create(
- user_id='user_id_123',
+ user_id='pg-user-550e8400-e29b-41d4',
toolkits=['github', 'slack', 'gmail']
)
@@ -35,7 +35,7 @@ session = composio.create(
```
```typescript TypeScript
-const { tools, mcp, authorize, toolkits } = await composio.create('user_id_123', {
+const { tools, mcp, authorize, toolkits } = await composio.create('pg-user-550e8400-e29b-41d4', {
toolkits: ['github', 'slack', 'gmail'],
});
diff --git a/fern/pages/src/tool-router/quickstart.mdx b/fern/pages/src/tool-router/quickstart.mdx
index 45adfaa93..f8b5db3ea 100644
--- a/fern/pages/src/tool-router/quickstart.mdx
+++ b/fern/pages/src/tool-router/quickstart.mdx
@@ -23,7 +23,7 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us
<Info>
`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).
-`user_123`: The [ID of the user](/docs/user-management) in your system.
+`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.
</Info>
```python
from composio import Composio
@@ -35,7 +35,7 @@ composio = Composio(
)
# Create a session for a user
-session = composio.create(user_id="user_123")
+session = composio.create(user_id="pg-user-550e8400-e29b-41d4")
```
</Step>
@@ -77,7 +77,7 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us
<Info>
`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).
-`user_123`: The [ID of the user](/docs/user-management) in your system.
+`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.
</Info>
```typescript
import { Composio } from "@composio/core";
@@ -89,7 +89,7 @@ const composio = new Composio({
});
// Create a session for a user
-const { tools } = await composio.create("user_123");
+const { tools } = await composio.create("pg-user-550e8400-e29b-41d4");
```
</Step>
@@ -131,7 +131,7 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us
<Info>
`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).
-`user_123`: The [ID of the user](/docs/user-management) in your system.
+`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.
</Info>
```python
from composio import Composio
@@ -143,7 +143,7 @@ composio = Composio(
)
# Create a session for a user
-session = composio.create(user_id="user_123")
+session = composio.create(user_id="pg-user-550e8400-e29b-41d4")
```
</Step>
@@ -185,7 +185,7 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us
<Info>
`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).
-`user_123`: The [ID of the user](/docs/user-management) in your system.
+`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.
</Info>
```typescript
import { Composio } from "@composio/core";
@@ -197,7 +197,7 @@ const composio = new Composio({
});
// Create a session for a user
-const { mcp } = await composio.create("user_123");
+const { mcp } = await composio.create("pg-user-550e8400-e29b-41d4");
```
</Step>
@@ -239,7 +239,7 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us
<Info>
`your-api-key`: Your Composio API key from the [dashboard](https://platform.composio.dev/?next_page=/settings).
-`user_123`: The [ID of the user](/docs/user-management) in your system.
+`pg-user-550e8400-e29b-41d4`: The [ID of the user](/docs/user-management) in your system.
</Info>
```typescript
import { Composio } from "@composio/core";
@@ -251,7 +251,7 @@ const composio = new Composio({
});
// Create a session for a user
-const { tools } = await composio.create("user_123");
+const { tools } = await composio.create("pg-user-550e8400-e29b-41d4");
```
</Step>
diff --git a/fern/pages/src/tool-router/users-and-sessions.mdx b/fern/pages/src/tool-router/users-and-sessions.mdx
index 057bb49aa..fa10cf7aa 100644
--- a/fern/pages/src/tool-router/users-and-sessions.mdx
+++ b/fern/pages/src/tool-router/users-and-sessions.mdx
@@ -1,8 +1,80 @@
---
-title: Users and Sessions
+title: Users and sessions
image: "https://og.composio.dev/api/og?title=Users%20and%20Sessions"
-description: ""
-keywords: ""
-subtitle: ""
+description: "Understand how Tool Router scopes tools and connections per user"
+keywords: "sessions, users, tool router, configuration"
hide-nav-links: false
---
+
+Sessions are ephemeral, user-scoped configurations that define what tools are available and how authentication works.
+
+## Users
+
+A user ID is an identifier from your system (database UUID, primary key) that Composio uses to scope connected accounts and tool access.
+
+<CodeGroup>
+```python Python
+session = composio.create(user_id="pg-user-550e8400-e29b-41d4")
+```
+
+```typescript TypeScript
+const session = await composio.create("pg-user-550e8400-e29b-41d4");
+```
+</CodeGroup>
+
+User IDs can represent individuals, teams, or organizations depending on your application. For detailed patterns, see [User Management](/docs/user-management).
+
+## Sessions
+
+A session defines the execution context for Tool Router's meta-tools. It combines:
+- Which user's connected accounts to use
+- Which toolkits are available
+- Which auth configs to use
+
+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.
+
+### Creating a session
+
+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.
+
+<CodeGroup>
+```python Python
+session = composio.create(
+ user_id="pg-user-550e8400-e29b-41d4",
+ toolkits=["github", "gmail", "slack"],
+ auth_configs={
+ "github": "ac_your_github_config"
+ }
+)
+```
+
+```typescript TypeScript
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
+ toolkits: ["github", "gmail", "slack"],
+ authConfigs: {
+ github: "ac_your_github_config",
+ },
+});
+```
+</CodeGroup>
+
+For all configuration options, see [Creating sessions](/tool-router/creating-sessions).
+
+### Connections persist
+
+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.
+
+Sessions configure *which* connections to use, but don't own the connections themselves.
+
+## Connected account precedence
+
+When executing a tool, Tool Router selects the connected account in this order:
+
+1. `connectedAccounts` override if provided in session config
+2. `authConfigs` override - finds or creates connection on that config
+3. Auth config previously created by Tool Router for this toolkit
+4. Creates new auth config using Composio managed auth (tagged as Tool Router created)
+5. Error if no Composio managed auth scheme exists for the toolkit
+
+If a user has multiple connected accounts for a toolkit, the most recently connected one is used.
+