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.

docs: add session methods, delete temporary file

Sushmithamalleshbe5f7183c78c
diff --git a/docs/content/docs/configuring-sessions.mdx b/docs/content/docs/configuring-sessions.mdx
index 9bceab526..bf2be867d 100644
--- a/docs/content/docs/configuring-sessions.mdx
+++ b/docs/content/docs/configuring-sessions.mdx
@@ -116,7 +116,7 @@ const session = await composio.create("user_123", {
</Tab>
</Tabs>
-See [White-labeling authentication](/docs/guides/white-labeling-authentication) for branding, or [Using custom auth configs](/docs/guides/using-custom-auth-configuration) for toolkits that require your own credentials.
+See [White-labeling authentication](/docs/white-labeling-authentication) for branding, or [Using custom auth configs](/docs/using-custom-auth-configuration) for toolkits that require your own credentials.
## Account selection
@@ -160,3 +160,114 @@ When executing a tool, the connected account is selected in this order:
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.
+
+## Session methods
+
+### mcp
+
+Get the MCP server URL to use with any MCP-compatible client.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+mcp_url = session.mcp.url
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+const session = await composio.create("user_123");
+// ---cut---
+const { mcp } = session;
+console.log(mcp.url);
+```
+</Tab>
+</Tabs>
+
+For framework examples, see provider-specific documentation like [OpenAI Agents](/docs/providers/openai-agents) or [Vercel AI SDK](/docs/providers/vercel).
+
+### tools()
+
+Get native tools from the session for use with AI frameworks.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+tools = session.tools()
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+const session = await composio.create("user_123");
+// ---cut---
+const tools = await session.tools();
+```
+</Tab>
+</Tabs>
+
+### authorize()
+
+Manually authenticate a user to a toolkit outside of the chat flow.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+connection_request = session.authorize("github")
+
+print(connection_request.redirect_url)
+
+connected_account = connection_request.wait_for_connection()
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+const session = await composio.create("user_123");
+// ---cut---
+const connectionRequest = await session.authorize("github", {
+ callbackUrl: "https://myapp.com/callback",
+});
+
+console.log(connectionRequest.redirectUrl);
+
+const connectedAccount = await connectionRequest.waitForConnection();
+```
+</Tab>
+</Tabs>
+
+For more details, see [Manually authenticating users](/docs/authenticating-users/manually-authenticating).
+
+### toolkits()
+
+List available toolkits and their connection status. You can use this to build a UI showing which apps are connected.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+toolkits = session.toolkits()
+
+for toolkit in toolkits.items:
+ status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"
+ print(f"{toolkit.name}: {status}")
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+const session = await composio.create("user_123");
+// ---cut---
+const toolkits = await session.toolkits();
+
+toolkits.items.forEach((toolkit) => {
+ console.log(`${toolkit.name}: ${toolkit.connection?.connectedAccount?.id ?? "Not connected"}`);
+});
+```
+</Tab>
+</Tabs>
+
+Returns the first 20 toolkits by default.
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index 81d8dde3b..bec034315 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -6,7 +6,6 @@
"quickstart-tool-router",
"providers",
"---Core Concepts---",
- "users-and-sessions-temporary",
"users-and-sessions",
"authentication",
"tools-and-toolkits",
diff --git a/docs/content/docs/users-and-sessions-temporary.mdx b/docs/content/docs/users-and-sessions-temporary.mdx
deleted file mode 100644
index b7880a76d..000000000
--- a/docs/content/docs/users-and-sessions-temporary.mdx
+++ /dev/null
@@ -1,286 +0,0 @@
----
-title: Users & Sessions Temporary
-description: Understand how Tool Router scopes tools and connections per user
-keywords: [session, user id, enable toolkits, disable toolkits]
----
-
-A **user ID** is an identifier from your system (database ID, UUID, or any unique string) that scopes connected accounts and tool access to a specific user. See [User Management](/docs/user-management) for best practices.
-
-A **session** is an ephemeral configuration that combines:
-- Which user's connected accounts to use
-- Which toolkits are available
-- Which auth configs to use
-
-Tool Router's meta-tools are the same for everyone. The session determines the context they operate within.
-
-## Creating a session
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
-<Tab value="Python">
-```python
-session = composio.create(user_id="user_123")
-```
-</Tab>
-<Tab value="TypeScript">
-```typescript
-import { Composio } from '@composio/core';
-const composio = new Composio({ apiKey: 'your_api_key' });
-// ---cut---
-const session = await composio.create("user_123");
-```
-</Tab>
-</Tabs>
-
-### Enabling toolkits
-
-Restrict the session to specific toolkits:
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
-<Tab value="Python">
-```python
-# Using array format
-session = composio.create(
- user_id="user_123",
- toolkits=["github", "gmail", "slack"]
-)
-
-# Using object format with enable key
-session = composio.create(
- user_id="user_123",
- toolkits={"enable": ["github", "gmail", "slack"]}
-)
-```
-</Tab>
-<Tab value="TypeScript">
-```typescript
-import { Composio } from '@composio/core';
-const composio = new Composio({ apiKey: 'your_api_key' });
-// ---cut---
-// Using array format
-const session = await composio.create("user_123", {
- toolkits: ["github", "gmail", "slack"],
-});
-
-// Using object format with enable key
-const session2 = await composio.create("user_123", {
- toolkits: { enable: ["github", "gmail", "slack"] },
-});
-```
-</Tab>
-</Tabs>
-
-### Disabling toolkits
-
-Keep all toolkits enabled except specific ones:
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
-<Tab value="Python">
-```python
-session = composio.create(
- user_id="user_123",
- toolkits={"disable": ["exa", "firecrawl"]}
-)
-```
-</Tab>
-<Tab value="TypeScript">
-```typescript
-import { Composio } from '@composio/core';
-const composio = new Composio({ apiKey: 'your_api_key' });
-// ---cut---
-const session = await composio.create("user_123", {
- toolkits: { disable: ["exa", "firecrawl"] },
-});
-```
-</Tab>
-</Tabs>
-
-### Custom auth configs
-
-Use your own OAuth credentials instead of Composio's defaults:
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
-<Tab value="Python">
-```python
-session = composio.create(
- user_id="user_123",
- auth_configs={
- "github": "ac_your_github_config",
- "slack": "ac_your_slack_config"
- }
-)
-```
-</Tab>
-<Tab value="TypeScript">
-```typescript
-import { Composio } from '@composio/core';
-const composio = new Composio({ apiKey: 'your_api_key' });
-// ---cut---
-const session = await composio.create("user_123", {
- authConfigs: {
- github: "ac_your_github_config",
- slack: "ac_your_slack_config",
- },
-});
-```
-</Tab>
-</Tabs>
-
-See [White-labeling authentication](/docs/guides/white-labeling-authentication) for branding, or [Using custom auth configs](/docs/guides/using-custom-auth-configuration) for toolkits that require your own credentials.
-
-## Connected accounts
-
-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.
-
-### Account selection
-
-If a user has multiple connected accounts for the same toolkit, you can specify which one to use:
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
-<Tab value="Python">
-```python
-session = composio.create(
- user_id="user_123",
- connected_accounts={
- "gmail": "ca_work_gmail",
- "github": "ca_personal_github"
- }
-)
-```
-</Tab>
-<Tab value="TypeScript">
-```typescript
-import { Composio } from '@composio/core';
-const composio = new Composio({ apiKey: 'your_api_key' });
-// ---cut---
-const session = await composio.create("user_123", {
- connectedAccounts: {
- gmail: "ca_work_gmail",
- github: "ca_personal_github",
- },
-});
-```
-</Tab>
-</Tabs>
-
-### 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.
-
-## Session methods
-
-### mcp
-
-Get the MCP server URL to use with any MCP-compatible client.
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
-<Tab value="Python">
-```python
-mcp_url = session.mcp.url
-```
-</Tab>
-<Tab value="TypeScript">
-```typescript
-import { Composio } from '@composio/core';
-const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
-// ---cut---
-const { mcp } = session;
-console.log(mcp.url);
-```
-</Tab>
-</Tabs>
-
-For framework examples, see provider-specific documentation like [OpenAI Agents](/docs/providers/openai-agents) or [Vercel AI SDK](/docs/providers/vercel).
-
-### tools()
-
-Get native tools from the session for use with AI frameworks.
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
-<Tab value="Python">
-```python
-tools = session.tools()
-```
-</Tab>
-<Tab value="TypeScript">
-```typescript
-import { Composio } from '@composio/core';
-const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
-// ---cut---
-const tools = await session.tools();
-```
-</Tab>
-</Tabs>
-
-### authorize()
-
-Manually authenticate a user to a toolkit outside of the chat flow.
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
-<Tab value="Python">
-```python
-connection_request = session.authorize("github")
-
-print(connection_request.redirect_url)
-
-connected_account = connection_request.wait_for_connection()
-```
-</Tab>
-<Tab value="TypeScript">
-```typescript
-import { Composio } from '@composio/core';
-const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
-// ---cut---
-const connectionRequest = await session.authorize("github", {
- callbackUrl: "https://myapp.com/callback",
-});
-
-console.log(connectionRequest.redirectUrl);
-
-const connectedAccount = await connectionRequest.waitForConnection();
-```
-</Tab>
-</Tabs>
-
-For more details, see [Manually authenticating users](/docs/authenticating-users/manually-authenticating).
-
-### toolkits()
-
-List available toolkits and their connection status. You can use this to build a UI showing which apps are connected.
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
-<Tab value="Python">
-```python
-toolkits = session.toolkits()
-
-for toolkit in toolkits.items:
- status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"
- print(f"{toolkit.name}: {status}")
-```
-</Tab>
-<Tab value="TypeScript">
-```typescript
-import { Composio } from '@composio/core';
-const composio = new Composio({ apiKey: 'your_api_key' });
-const session = await composio.create("user_123");
-// ---cut---
-const toolkits = await session.toolkits();
-
-toolkits.items.forEach((toolkit) => {
- console.log(`${toolkit.name}: ${toolkit.connection?.connectedAccount?.id ?? "Not connected"}`);
-});
-```
-</Tab>
-</Tabs>
-
-Returns the first 20 toolkits by default.
diff --git a/docs/content/docs/users-and-sessions.mdx b/docs/content/docs/users-and-sessions.mdx
index 70517f1e3..23d7fae14 100644
--- a/docs/content/docs/users-and-sessions.mdx
+++ b/docs/content/docs/users-and-sessions.mdx
@@ -53,6 +53,47 @@ const session = await composio.create("user_123");
</Tab>
</Tabs>
-For details on enabling toolkits, setting auth configs, and selecting connected accounts:
+### Session methods
+
+Once created, a session provides methods to get tools and manage connections:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+# Get tools for your AI framework
+tools = session.tools()
+
+# Get MCP server URL
+mcp_url = session.mcp.url
+
+# Authenticate a user to a toolkit
+connection_request = session.authorize("github")
+
+# List available toolkits and their connection status
+toolkits = session.toolkits()
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+const session = await composio.create("user_123");
+// ---cut---
+// Get tools for your AI framework
+const tools = await session.tools();
+
+// Get MCP server URL
+const mcpUrl = session.mcp.url;
+
+// Authenticate a user to a toolkit
+const connectionRequest = await session.authorize("github");
+
+// List available toolkits and their connection status
+const toolkits = await session.toolkits();
+```
+</Tab>
+</Tabs>
+
+For details on enabling toolkits, setting auth configs, and using session methods:
<Card title="Configuring Sessions" href="/docs/configuring-sessions" description="Enable toolkits, set auth configs, and select connected accounts" />