Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
manual authenitcate fixes
Sushmithamallesh committed
Dec 12, 2025 at 16:43 UTC
75bd7bbb8f7df74f0bc8d27cb96787f8751dd2ea
3 files changed
+68
-142
fern/pages/src/tool-router/manually-authenticating-users.mdx
+39
-81
@@ -9,125 +9,83 @@ Manual authentication lets you connect users to toolkits outside of the chat flo
9
- Pre-authenticate users before they start chatting
10
- Build a custom connections UI in your app
11
12
-## Create session
12
+## Authorize a toolkit
13
14
-Disable the `COMPOSIO_MANAGE_CONNECTIONS` meta-tool so the agent doesn't prompt for auth during chat:
14
+Use `session.authorize()` to generate a [Connect Link](/docs/authenticating-tools#hosted-authentication-connect-link) URL, redirect the user, and wait for them to complete:
15
16
<CodeGroup>
17
```python
18
-session = composio.create(
19
- user_id="user_123",
20
- manage_connections=False,
21
-)
18
+session = composio.create(user_id="user_123")
19
+
20
+connection_request = session.authorize("gmail")
21
+
22
+print(connection_request.redirect_url)
23
+# https://connect.composio.dev/link/ln_abc123
24
+
25
+connected_account = connection_request.wait_for_connection(60000)
26
+print(f"Connected: {connected_account.id}")
27
```
28
```typescript
24
-const session = await composio.create("user_123", {
25
- manageConnections: false,
26
-});
29
+const session = await composio.create("user_123");
30
+
31
+const connectionRequest = await session.authorize("gmail");
32
+
33
+console.log(connectionRequest.redirectUrl);
34
+// https://connect.composio.dev/link/ln_abc123
35
+
36
+const connectedAccount = await connectionRequest.waitForConnection(60000);
37
+console.log(`Connected: ${connectedAccount.id}`);
38
```
39
</CodeGroup>
40
41
+Redirect the user to the redirect URL. After they authenticate, they'll return to your callback URL. The connection request polls until the user completes authentication (default timeout: 60 seconds).
42
+
43
+<Note>
44
+If the user closes the Connect Link without completing auth, the connection remains in `INITIATED` status until it expires.
45
+</Note>
46
+
47
## Check connection status
48
32
-Use `session.toolkits()` to see which apps the user has connected:
49
+Use `session.toolkits()` to see all toolkits in the session and their connection status:
50
51
<CodeGroup>
52
```python
53
toolkits = session.toolkits()
54
38
-for toolkit in toolkits:
39
- status = toolkit.connected_account.status if toolkit.connected_account else "Not connected"
55
+for toolkit in toolkits.items:
56
+ status = toolkit.connection.connected_account.id if toolkit.connection.is_active else "Not connected"
57
print(f"{toolkit.name}: {status}")
58
```
59
```typescript
60
const toolkits = await session.toolkits();
61
45
-for (const toolkit of toolkits) {
46
- const status = toolkit.connectedAccount?.status || "Not connected";
47
- console.log(`${toolkit.name}: ${status}`);
48
-}
49
-```
50
-</CodeGroup>
51
-
52
-Each toolkit includes:
53
-- `name`, `slug`, `logo`, `description`
54
-- `connectedAccount` - present if user is connected, includes `id`, `status`, `createdAt`
55
-
56
-### Filter and sort
57
-
58
-Use filters to show relevant toolkits in your UI:
59
-
60
-<CodeGroup>
61
-```python
62
-toolkits = session.toolkits(
63
- order_by="popularity", # Sort by most used
64
- order_direction="desc",
65
- category="developer-tools", # Filter by category
66
- is_connected=True, # Only show connected apps
67
-)
68
-```
69
-```typescript
70
-const toolkits = await session.toolkits({
71
- orderBy: "popularity", // Sort by most used
72
- orderDirection: "desc",
73
- category: "developer-tools", // Filter by category
74
- isConnected: true, // Only show connected apps
62
+toolkits.items.forEach((toolkit) => {
63
+ console.log(`${toolkit.name}: ${toolkit.connection.connectedAccount?.id ?? "Not connected"}`);
64
});
65
```
66
</CodeGroup>
67
79
-## Generate auth URL
68
+## Disabling in-chat auth
69
81
-Use `session.authorize()` to generate a [Connect Link](/docs/authenticating-tools#hosted-authentication-connect-link) URL:
70
+By default, Tool Router includes the `COMPOSIO_MANAGE_CONNECTIONS` meta-tool that prompts users to authenticate during chat. To disable this and handle auth entirely in your UI:
71
72
<CodeGroup>
73
```python
85
-connection_request = session.authorize(
86
- "gmail",
87
- callback_url="https://yourapp.com/callback"
74
+session = composio.create(
75
+ user_id="user_123",
76
+ manage_connections=False,
77
)
89
-
90
-print(connection_request.redirect_url)
91
-# https://connect.composio.dev/link/ln_abc123
78
```
79
```typescript
94
-const connectionRequest = await session.authorize("gmail", {
95
- callbackUri: "https://yourapp.com/callback",
80
+const session = await composio.create("user_123", {
81
+ manageConnections: false,
82
});
97
-
98
-console.log(connectionRequest.redirectUrl);
99
-// https://connect.composio.dev/link/ln_abc123
83
```
84
</CodeGroup>
85
103
-Redirect the user to `redirectUrl`. After they authenticate, they'll be redirected to your `callbackUrl`.
104
-
105
-## Wait for connection
106
-
107
-Use `waitForConnection()` to poll until the user completes authentication:
108
-
109
-<CodeGroup>
110
-```python
111
-connected_account = connection_request.wait_for_connection(60000)
112
-print(f"Connected: {connected_account.id}")
113
-```
114
-```typescript
115
-const connectedAccount = await connectionRequest.waitForConnection(60000);
116
-console.log(`Connected: ${connectedAccount.id}`);
117
-```
118
-</CodeGroup>
119
-
120
-- Default timeout: 60 seconds (60000ms)
121
-- Throws `ConnectionRequestTimeoutError` if timeout expires
122
-- Throws `ConnectionRequestFailedError` if connection fails or expires
123
-
124
-<Note>
125
-If the user closes the Connect Link without completing auth, the connection remains in `INITIATED` status until it expires.
126
-</Note>
127
-
86
## Putting it together
87
130
-A common pattern is to verify all required connections before starting the agent. For example, a personal assistant might need Gmail, Calendar, Linear, and Slack:
88
+A common pattern is to verify all required connections before starting the agent:
89
90
<CodeGroup>
91
<SnippetCode src="fern/snippets/tool-router/python/manual-auth.py" title="Python" />
fern/snippets/tool-router/python/manual-auth.py
+15
-36
@@ -1,46 +1,25 @@
1
from composio import Composio
2
-from agents import Agent, Runner, HostedMCPTool
2
4
-composio = Composio()
3
+composio = Composio(api_key="your-api-key")
4
6
-required_toolkits = ["gmail", "googlecalendar", "linear", "slack"]
5
+required_toolkits = ["gmail", "github"]
6
7
session = composio.create(
9
- user_id=user_id,
10
- manage_connections=False,
8
+ user_id="user_123",
9
+ manage_connections=False, # Disable in-chat auth prompts
10
)
11
12
toolkits = session.toolkits()
13
15
-def is_connected(slug):
16
- toolkit = next((t for t in toolkits if t.slug == slug), None)
17
- return toolkit and toolkit.connected_account
18
-
19
-pending = [slug for slug in required_toolkits if not is_connected(slug)]
20
-
21
-if pending:
22
- for slug in pending:
23
- connection_request = session.authorize(
24
- slug,
25
- callback_url="https://yourapp.com/onboarding"
26
- )
27
- print(f"Connect {slug}: {connection_request.redirect_url}")
28
- connection_request.wait_for_connection()
29
-
30
-agent = Agent(
31
- name="Personal Assistant",
32
- instructions="You are a helpful personal assistant.",
33
- tools=[
34
- HostedMCPTool(
35
- tool_config={
36
- "type": "mcp",
37
- "server_label": "composio",
38
- "server_url": session.mcp.url,
39
- "require_approval": "never",
40
- }
41
- )
42
- ],
43
-)
14
+connected = {t.slug for t in toolkits.items if t.connection.is_active}
15
+pending = [slug for slug in required_toolkits if slug not in connected]
16
+
17
+print(f"Connected: {connected}")
18
+print(f"Pending: {pending}")
19
+
20
+for slug in pending:
21
+ connection_request = session.authorize(slug)
22
+ print(f"Connect {slug}: {connection_request.redirect_url}")
23
+ connection_request.wait_for_connection()
24
45
-result = Runner.run_sync(agent, "Summarize my emails from today")
46
-print(result.final_output)
25
+print(f"All toolkits connected! MCP URL: {session.mcp.url}")
fern/snippets/tool-router/typescript/manual-auth.ts
+14
-25
@@ -1,39 +1,28 @@
1
import { Composio } from "@composio/core";
2
-import { Agent, run, hostedMcpTool } from "@openai/agents";
2
4
-const composio = new Composio();
3
+const composio = new Composio({ apiKey: "your-api-key" });
4
6
-const requiredToolkits = ["gmail", "googlecalendar", "linear", "slack"];
5
+const requiredToolkits = ["gmail", "github"];
6
8
-const session = await composio.create(userId, {
9
- manageConnections: false,
7
+const session = await composio.create("user_123", {
8
+ manageConnections: false, // Disable in-chat auth prompts
9
});
10
11
const toolkits = await session.toolkits();
12
14
-const pending = requiredToolkits.filter((slug) => {
15
- const toolkit = toolkits.find((t) => t.slug === slug);
16
- return !toolkit?.connectedAccount;
17
-});
13
+const connected = toolkits.items
14
+ .filter((t) => t.connection.connectedAccount)
15
+ .map((t) => t.slug);
16
+
17
+const pending = requiredToolkits.filter((slug) => !connected.includes(slug));
18
+
19
+console.log("Connected:", connected);
20
+console.log("Pending:", pending);
21
22
for (const slug of pending) {
20
- const connectionRequest = await session.authorize(slug, {
21
- callbackUri: "https://yourapp.com/onboarding",
22
- });
23
+ const connectionRequest = await session.authorize(slug);
24
console.log(`Connect ${slug}: ${connectionRequest.redirectUrl}`);
25
await connectionRequest.waitForConnection();
26
}
27
27
-const agent = new Agent({
28
- name: "Personal Assistant",
29
- instructions: "You are a helpful personal assistant.",
30
- tools: [
31
- hostedMcpTool({
32
- serverLabel: "composio",
33
- serverUrl: session.mcp.url,
34
- }),
35
- ],
36
-});
37
-
38
-const result = await run(agent, "Summarize my emails from today");
39
-console.log(result.finalOutput);
28
+console.log(`All toolkits connected! MCP URL: ${session.mcp.url}`);