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

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>