Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
fix custom auth stuff
Sushmithamallesh committed
Dec 3, 2025 at 16:55 UTC
f1c80ecb95b3a91781014d83caf915d1e0a7b5ce
7 files changed
+151
-150
fern/docs.yml
+4
-4
@@ -305,12 +305,9 @@ navigation:
305
icon: fa-light fa-book
306
skip-slug: true
307
contents:
308
- - page: Creating Sessions
308
+ - page: Session Configuration
309
path: pages/dist/tool-router/creating-sessions.mdx
310
slug: creating-sessions
311
- - page: Configuring Toolkits
312
- path: pages/dist/tool-router/configuring-toolkits.mdx
313
- slug: configuring-toolkits
311
- page: Using In-chat Authentication
312
path: pages/dist/tool-router/using-in-chat-authentication.mdx
313
slug: using-in-chat-authentication
@@ -320,6 +317,9 @@ navigation:
317
- page: White-labeling Authentication
318
path: pages/dist/tool-router/white-labeling-authentication.mdx
319
slug: white-labeling-authentication
320
+ - page: Configuring Custom Auth Configs
321
+ path: pages/dist/tool-router/configuring-custom-auth-configs.mdx
322
+ slug: configuring-custom-auth-configs
323
- page: Configuring Workbench
324
path: pages/dist/tool-router/configuring-workbench.mdx
325
slug: configuring-workbench
fern/pages/src/tool-router/authentication.mdx
+1
-1
@@ -45,7 +45,7 @@ Tool Router can automatically create auth configs for:
45
- **API key auth** - Users provide their own API keys via Connect Link.
46
47
<Note>
48
-Toolkits without Composio managed auth require you to [create an auth config](/docs/authenticating-tools#creating-an-auth-config) first and pass it via `authConfigs`.
48
+Toolkits without Composio managed auth require you to create an auth config first. See [Configuring custom auth configs](/docs/tool-router/configuring-custom-auth-configs).
49
</Note>
50
51
## White-labeling
fern/pages/src/tool-router/configuring-custom-auth-configs.mdx
new
+53
@@ -0,0 +1,53 @@
1
+---
2
+title: Configuring custom auth configs
3
+image: "https://og.composio.dev/api/og?title=Configuring%20Custom%20Auth%20Configs"
4
+description: "Set up auth configs for toolkits without Composio managed authentication"
5
+keywords: "tool router, auth config, custom credentials, oauth"
6
+---
7
+
8
+Some toolkits don't have Composio managed authentication and require you to provide your own credentials. When Tool Router tries to use these toolkits, it will throw an error asking you to create an auth config.
9
+
10
+<Steps>
11
+<Step title="Check if a toolkit needs custom credentials">
12
+In the [Composio platform](https://platform.composio.dev), go to "All Toolkits" and select the toolkit. If it shows no Composio managed auth schemes, you'll need to create an auth config.
13
+</Step>
14
+
15
+<Step title="Create an auth config">
16
+1. Go to **Authentication management** in the [dashboard](https://app.composio.dev)
17
+2. Click **Create Auth Config**
18
+3. Select the toolkit
19
+4. Choose the auth scheme (OAuth2, API Key, etc.)
20
+5. Enter your credentials (client ID, client secret, API key, etc.)
21
+6. Click **Create**
22
+
23
+Copy the auth config ID (e.g., `ac_1234abcd`).
24
+
25
+<Tip>
26
+For detailed instructions on getting credentials for specific toolkits, see [Custom auth configs](/docs/authentication/custom-auth-configs).
27
+</Tip>
28
+</Step>
29
+
30
+<Step title="Use in Tool Router">
31
+Pass your auth config ID when creating a session:
32
+
33
+<CodeGroup>
34
+```python
35
+session = composio.create(
36
+ user_id="pg-user-550e8400-e29b-41d4",
37
+ auth_configs={
38
+ "posthog": "ac_your_posthog_config"
39
+ }
40
+)
41
+```
42
+```typescript
43
+const session = await composio.create("pg-user-550e8400-e29b-41d4", {
44
+ authConfigs: {
45
+ posthog: "ac_your_posthog_config",
46
+ },
47
+});
48
+```
49
+</CodeGroup>
50
+
51
+Tool Router will now use your auth config when users connect to this toolkit.
52
+</Step>
53
+</Steps>
fern/pages/src/tool-router/configuring-toolkits.mdx
deleted
-7
@@ -1,7 +0,0 @@
1
----
2
-title: Configuring Toolkits
3
-image: "https://og.composio.dev/api/og?title=Configuring%20Toolkits"
4
-description: "Configure which toolkits are available in a session"
5
-keywords: "tool router"
6
----
7
-
fern/pages/src/tool-router/creating-sessions.mdx
+47
-123
@@ -1,26 +1,24 @@
1
---
2
-title: Creating sessions
3
-image: "https://og.composio.dev/api/og?title=Creating%20Sessions"
2
+title: Session configuration
3
+image: "https://og.composio.dev/api/og?title=Session%20Configuration"
4
description: "Configure toolkits, authentication, and connections for a session"
5
-keywords: "sessions, create session, tool router, configuration"
5
+keywords: "sessions, create session, tool router, configuration, configuring toolkits"
6
hide-nav-links: false
7
---
8
9
-Create a session to configure what tools are available and how authentication works for a user.
9
+Sessions are ephemeral, user-scoped containers that manage which tools are available and how authentication works.
10
11
-## Basic session
12
-
13
-Create a session with all available toolkits:
11
+## Creating a session
12
13
<CodeGroup>
16
-```python Python
14
+```python
15
from composio import Composio
16
17
composio = Composio(api_key="your-api-key")
18
session = composio.create(user_id="pg-user-550e8400-e29b-41d4")
19
```
20
23
-```typescript TypeScript
21
+```typescript
22
import { Composio } from "@composio/core";
23
24
const composio = new Composio({ apiKey: "your-api-key" });
@@ -28,54 +26,52 @@ const session = await composio.create("pg-user-550e8400-e29b-41d4");
26
```
27
</CodeGroup>
28
31
-## Configuration options
29
+By default, all toolkits are available and in-chat authentication is enabled.
30
33
-### toolkits
31
+## Toolkit access
32
35
-Restrict which toolkits are available in the session.
36
-
37
-**Enable specific toolkits:**
33
+### Allow specific toolkits
34
35
<CodeGroup>
40
-```python Python
36
+```python
37
session = composio.create(
38
user_id="pg-user-550e8400-e29b-41d4",
39
toolkits=["github", "gmail", "slack"]
40
)
41
```
42
47
-```typescript TypeScript
43
+```typescript
44
const session = await composio.create("pg-user-550e8400-e29b-41d4", {
45
toolkits: ["github", "gmail", "slack"],
46
});
47
```
48
</CodeGroup>
49
54
-**Disable specific toolkits:**
50
+### Disable specific toolkits
51
52
<CodeGroup>
57
-```python Python
53
+```python
54
session = composio.create(
55
user_id="pg-user-550e8400-e29b-41d4",
56
toolkits={"disable": ["exa", "firecrawl"]}
57
)
58
```
59
64
-```typescript TypeScript
60
+```typescript
61
const session = await composio.create("pg-user-550e8400-e29b-41d4", {
62
toolkits: { disable: ["exa", "firecrawl"] },
63
});
64
```
65
</CodeGroup>
66
71
-### authConfigs
67
+## Authentication
68
+
69
+### Custom OAuth apps
70
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
71
+Use your own OAuth credentials instead of Composio's defaults. See [White-labeling authentication](/tool-router/white-labeling-authentication) for branding, or [Configuring custom auth configs](/tool-router/configuring-custom-auth-configs) for toolkits that require your own credentials.
72
73
<CodeGroup>
78
-```python Python
74
+```python
75
session = composio.create(
76
user_id="pg-user-550e8400-e29b-41d4",
77
auth_configs={
@@ -85,7 +81,7 @@ session = composio.create(
81
)
82
```
83
88
-```typescript TypeScript
84
+```typescript
85
const session = await composio.create("pg-user-550e8400-e29b-41d4", {
86
authConfigs: {
87
github: "ac_your_github_config",
@@ -95,16 +91,12 @@ const session = await composio.create("pg-user-550e8400-e29b-41d4", {
91
```
92
</CodeGroup>
93
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
94
+### Account selection
95
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"
96
+Specify which connected account to use when a user has multiple accounts for the same toolkit.
97
98
<CodeGroup>
107
-```python Python
99
+```python
100
session = composio.create(
101
user_id="pg-user-550e8400-e29b-41d4",
102
connected_accounts={
@@ -114,7 +106,7 @@ session = composio.create(
106
)
107
```
108
117
-```typescript TypeScript
109
+```typescript
110
const session = await composio.create("pg-user-550e8400-e29b-41d4", {
111
connectedAccounts: {
112
gmail: "ca_work_gmail",
@@ -124,27 +116,21 @@ const session = await composio.create("pg-user-550e8400-e29b-41d4", {
116
```
117
</CodeGroup>
118
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
119
+### In-chat prompts
120
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
121
+Control whether the agent can prompt users to connect accounts during chat.
122
123
**Disable in-chat authentication:**
124
125
<CodeGroup>
140
-```python Python
126
+```python
127
session = composio.create(
128
user_id="pg-user-550e8400-e29b-41d4",
129
manage_connections=False
130
)
131
```
132
147
-```typescript TypeScript
133
+```typescript
134
const session = await composio.create("pg-user-550e8400-e29b-41d4", {
135
manageConnections: false,
136
});
@@ -154,14 +140,14 @@ const session = await composio.create("pg-user-550e8400-e29b-41d4", {
140
**Custom callback URL:**
141
142
<CodeGroup>
157
-```python Python
143
+```python
144
session = composio.create(
145
user_id="pg-user-550e8400-e29b-41d4",
146
manage_connections={"callback_url": "https://myapp.com/callback"}
147
)
148
```
149
164
-```typescript TypeScript
150
+```typescript
151
const session = await composio.create("pg-user-550e8400-e29b-41d4", {
152
manageConnections: { callbackUrl: "https://myapp.com/callback" },
153
});
@@ -170,61 +156,14 @@ const session = await composio.create("pg-user-550e8400-e29b-41d4", {
156
157
For more details, see [Using in-chat authentication](/tool-router/using-in-chat-authentication) and [Manually authenticating users](/tool-router/manually-authenticating-users).
158
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
159
+## Session methods
160
161
### tools()
162
163
Get meta-tools to pass to your agent framework.
164
165
<CodeGroup>
227
-```python Python
166
+```python
167
tools = session.tools()
168
169
agent = Agent(
@@ -234,7 +173,7 @@ agent = Agent(
173
)
174
```
175
237
-```typescript TypeScript
176
+```typescript
177
const tools = await session.tools();
178
179
const agent = new Agent({
@@ -252,41 +191,24 @@ For framework-specific examples, see [Using as native tools](/tool-router/using-
191
Get the MCP server URL to use with any MCP-compatible client.
192
193
<CodeGroup>
255
-```python Python
194
+```python
195
mcp_url = session.mcp.url
196
```
197
259
-```typescript TypeScript
198
+```typescript
199
const { mcp } = session;
200
console.log(mcp.url);
201
```
202
</CodeGroup>
203
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).
204
+For framework examples, see [Using with MCP clients](/tool-router/using-with-mcp-clients).
205
206
### authorize()
207
286
-[Manually authenticate](/tool-router/manually-authenticating-users) a user to a toolkit outside of the chat flow.
208
+Manually authenticate a user to a toolkit outside of the chat flow.
209
210
<CodeGroup>
289
-```python Python
211
+```python
212
connection_request = session.authorize(
213
"github",
214
callback_url="https://myapp.com/callback"
@@ -297,7 +219,7 @@ print(connection_request.redirect_url)
219
connected_account = connection_request.wait_for_connection()
220
```
221
300
-```typescript TypeScript
222
+```typescript
223
const connectionRequest = await session.authorize("github", {
224
callbackUrl: "https://myapp.com/callback",
225
});
@@ -308,22 +230,25 @@ const connectedAccount = await connectionRequest.waitForConnection();
230
```
231
</CodeGroup>
232
233
+For more details, see [Manually authenticating users](/tool-router/manually-authenticating-users).
234
+
235
### toolkits()
236
313
-List available toolkits and their connection status for the session. Use this to build a UI showing which apps are connected.
237
+List available toolkits and their connection status. Use this to build a UI showing which apps are connected.
238
239
<CodeGroup>
316
-```python Python
240
+```python
241
toolkits = session.toolkits(
242
order_by="popularity",
243
is_connected=True
244
)
245
246
for toolkit in toolkits:
323
- print(f"{toolkit.name}: {toolkit.connected_account.id if toolkit.connected_account else 'Not connected'}")
247
+ status = toolkit.connected_account.id if toolkit.connected_account else "Not connected"
248
+ print(f"{toolkit.name}: {status}")
249
```
250
326
-```typescript TypeScript
251
+```typescript
252
const toolkits = await session.toolkits({
253
orderBy: "popularity",
254
isConnected: true,
@@ -339,4 +264,3 @@ toolkits.forEach((toolkit) => {
264
- `orderBy`: `"popularity"`, `"name"`, or `"connected_at"`
265
- `isConnected`: `true` to show only connected toolkits
266
- `category`: Filter by category (e.g., `"productivity"`, `"communication"`)
342
-
fern/pages/src/tool-router/quickstart.mdx
+4
-12
@@ -122,7 +122,7 @@ To use OpenAI Agents SDK with Tool Router MCP instead, see [Using with MCP Clien
122
<Steps>
123
<Step title="Install Composio SDK">
124
```bash
125
-pip install composio anthropic-agents composio-anthropic
125
+pip install composio anthropic-agents
126
```
127
</Step>
128
@@ -135,12 +135,8 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us
135
</Info>
136
```python
137
from composio import Composio
138
-from composio_anthropic import AnthropicProvider
138
140
-composio = Composio(
141
- api_key="your-api-key",
142
- provider=AnthropicProvider()
143
-)
139
+composio = Composio(api_key="your-api-key")
140
141
# Create a session for a user
142
session = composio.create(user_id="pg-user-550e8400-e29b-41d4")
@@ -176,7 +172,7 @@ To use Anthropic Agents SDK with Tool Router as native tools instead, see [Using
172
<Steps>
173
<Step title="Install Composio SDK">
174
```bash
179
-npm install @composio/core @composio/anthropic @anthropic-ai/agent
175
+npm install @composio/core @anthropic-ai/agent
176
```
177
</Step>
178
@@ -189,12 +185,8 @@ Sessions are ephemeral, user-scoped and manage connections and tools for that us
185
</Info>
186
```typescript
187
import { Composio } from "@composio/core";
192
-import { AnthropicProvider } from "@composio/anthropic";
188
194
-const composio = new Composio({
195
- apiKey: "your-api-key",
196
- provider: new AnthropicProvider(),
197
-});
189
+const composio = new Composio({ apiKey: "your-api-key" });
190
191
// Create a session for a user
192
const { mcp } = await composio.create("pg-user-550e8400-e29b-41d4");
fern/pages/src/tool-router/tools-and-toolkits.mdx
+42
-3
@@ -1,7 +1,46 @@
1
---
2
-title: Tools and Toolkits
2
+title: Tools and toolkits
3
image: "https://og.composio.dev/api/og?title=Tools%20and%20Toolkits"
4
-description: "Managing tools and toolkits in Tool Router"
5
-keywords: "tool router"
4
+description: "Access 800+ integrations through Tool Router"
5
+keywords: "tool router, tools, toolkits, integrations, composio"
6
---
7
8
+Tool Router gives your agent access to most Composio toolkits by default. For details on configuring which toolkits and tools are available in a session, see [Session configuration](/tool-router/creating-sessions).
9
+
10
+## Toolkits and tools
11
+
12
+A **toolkit** is a collection of related tools for a service and a **tool** is an individual action your agent can execute.
13
+For example, the `github` toolkit contains tools like `GITHUB_CREATE_A_COMMIT`, `GITHUB_ACTIVITY_LIST_STARGAZERS_FOR_REPO`, and `GITHUB_SEARCH_REPO_S`.
14
+
15
+## Available toolkits
16
+
17
+Browse all available toolkits in the [Composio platform](https://platform.composio.dev) under "All Toolkits". Each toolkit page shows its tools (with input and output parameters) and authentication methods supported for that toolkit.
18
+
19
+<Note>
20
+Some toolkits require you to provide your own credentials. See [Configuring custom auth configs](/tool-router/configuring-custom-auth-configs).
21
+</Note>
22
+
23
+<Tip>
24
+Need a toolkit that doesn't exist? [Request it here](https://request.composio.dev/boards/tool-requests).
25
+</Tip>
26
+
27
+For details on browsing tools within toolkits and inspecting schemas, see [Fetching tools and schemas](/docs/fetching-tools).
28
+
29
+## Default behavior
30
+
31
+When you create a session, all toolkits are available:
32
+
33
+<CodeGroup>
34
+```python
35
+session = composio.create(user_id="pg-user-550e8400-e29b-41d4")
36
+```
37
+```typescript
38
+const session = await composio.create("pg-user-550e8400-e29b-41d4");
39
+```
40
+</CodeGroup>
41
+
42
+Your agent can search and use tools from any toolkit. To restrict or configure which toolkits are available, see [Session configuration](/docs/tool-router/creating-sessions).
43
+
44
+<Tip>
45
+Triggers can be used alongside Tool Router to respond to events in connected apps. See [Using triggers](/docs/tools-and-triggers/using-triggers) for setup instructions.
46
+</Tip>