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 auth fixes
Sushmithamallesh committed
Nov 30, 2025 at 01:11 UTC
6082f003839a93b17874ccfcbfac4e4cfb7d7928
4 files changed
+345
-15
fern/pages/src/tool-router/manually-authenticating-users.mdx
+224
-3
@@ -1,7 +1,228 @@
1
---
2
-title: Manually Authenticating Users
2
+title: Manually authenticating users
3
image: "https://og.composio.dev/api/og?title=Manually%20Authenticating%20Users"
4
-description: "Programmatically authenticate users to toolkits"
5
-keywords: "tool router"
4
+description: "Authenticate users to toolkits outside of chat"
5
+keywords: "tool router, authentication, manual, authorize, toolkits"
6
---
7
8
+Manual authentication lets you connect users to toolkits outside of the chat flow. Use this when you want to:
9
+- Pre-authenticate users before they start chatting
10
+- Build a custom connections UI in your app
11
+
12
+## Create session
13
+
14
+Disable the `COMPOSIO_MANAGE_CONNECTIONS` meta-tool so the agent doesn't prompt for auth during chat:
15
+
16
+<CodeGroup>
17
+```python
18
+session = await composio.create_session(
19
+ user="pg-user-550e8400-e29b-41d4",
20
+ manage_connections=False,
21
+)
22
+```
23
+```typescript
24
+const session = await composio.createSession({
25
+ user: "pg-user-550e8400-e29b-41d4",
26
+ manageConnections: false,
27
+});
28
+```
29
+</CodeGroup>
30
+
31
+## Check connection status
32
+
33
+Use `session.toolkits()` to see which apps the user has connected:
34
+
35
+<CodeGroup>
36
+```python
37
+toolkits = await session.toolkits()
38
+
39
+for toolkit in toolkits:
40
+ status = toolkit.connected_account.status if toolkit.connected_account else "Not connected"
41
+ print(f"{toolkit.name}: {status}")
42
+```
43
+```typescript
44
+const toolkits = await session.toolkits();
45
+
46
+for (const toolkit of toolkits) {
47
+ const status = toolkit.connectedAccount?.status || "Not connected";
48
+ console.log(`${toolkit.name}: ${status}`);
49
+}
50
+```
51
+</CodeGroup>
52
+
53
+Each toolkit includes:
54
+- `name`, `slug`, `logo`, `description`
55
+- `connectedAccount` - present if user is connected, includes `id`, `status`, `createdAt`
56
+
57
+### Filter and sort
58
+
59
+Use filters to show relevant toolkits in your UI:
60
+
61
+<CodeGroup>
62
+```python
63
+toolkits = await session.toolkits(
64
+ order_by="popularity", # Sort by most used
65
+ order_direction="desc",
66
+ category="developer-tools", # Filter by category
67
+ is_connected=True, # Only show connected apps
68
+)
69
+```
70
+```typescript
71
+const toolkits = await session.toolkits({
72
+ orderBy: "popularity", // Sort by most used
73
+ orderDirection: "desc",
74
+ category: "developer-tools", // Filter by category
75
+ isConnected: true, // Only show connected apps
76
+});
77
+```
78
+</CodeGroup>
79
+
80
+## Generate auth URL
81
+
82
+Use `session.authorize()` to generate a [Connect Link](/docs/authenticating-tools#hosted-authentication-connect-link) URL:
83
+
84
+<CodeGroup>
85
+```python
86
+connection_request = await session.authorize(
87
+ "gmail",
88
+ callback_url="https://yourapp.com/callback"
89
+)
90
+
91
+print(connection_request.redirect_url)
92
+# https://connect.composio.dev/link/ln_abc123
93
+```
94
+```typescript
95
+const connectionRequest = await session.authorize("gmail", {
96
+ callbackUrl: "https://yourapp.com/callback",
97
+});
98
+
99
+console.log(connectionRequest.redirectUrl);
100
+// https://connect.composio.dev/link/ln_abc123
101
+```
102
+</CodeGroup>
103
+
104
+Redirect the user to `redirectUrl`. After they authenticate, they'll be redirected to your `callbackUrl`.
105
+
106
+## Wait for connection
107
+
108
+Use `waitForConnection()` to poll until the user completes authentication:
109
+
110
+<CodeGroup>
111
+```python
112
+connected_account = await connection_request.wait_for_connection(60000)
113
+print(f"Connected: {connected_account.id}")
114
+```
115
+```typescript
116
+const connectedAccount = await connectionRequest.waitForConnection(60000);
117
+console.log(`Connected: ${connectedAccount.id}`);
118
+```
119
+</CodeGroup>
120
+
121
+- Default timeout: 60 seconds (60000ms)
122
+- Throws `ConnectionRequestTimeoutError` if timeout expires
123
+- Throws `ConnectionRequestFailedError` if connection fails or expires
124
+
125
+<Note>
126
+If the user closes the Connect Link without completing auth, the connection remains in `INITIATED` status until it expires.
127
+</Note>
128
+
129
+## Putting it together
130
+
131
+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:
132
+
133
+<CodeGroup>
134
+```python
135
+required_toolkits = ["gmail", "googlecalendar", "linear", "slack"]
136
+
137
+session = await composio.create_session(
138
+ user=user_id,
139
+ manage_connections=False,
140
+)
141
+
142
+toolkits = await session.toolkits()
143
+
144
+def is_connected(slug):
145
+ toolkit = next((t for t in toolkits if t.slug == slug), None)
146
+ return toolkit and toolkit.connected_account
147
+
148
+pending = [slug for slug in required_toolkits if not is_connected(slug)]
149
+
150
+if pending:
151
+ for slug in pending:
152
+ connection_request = await session.authorize(
153
+ slug,
154
+ callback_url="https://yourapp.com/onboarding"
155
+ )
156
+ # Show connection_request.redirect_url to user
157
+
158
+ # Wait for all connections before continuing
159
+
160
+# All apps connected, start the agent
161
+tools = await session.tools()
162
+```
163
+```typescript
164
+const requiredToolkits = ["gmail", "googlecalendar", "linear", "slack"];
165
+
166
+const session = await composio.createSession({
167
+ user: userId,
168
+ manageConnections: false,
169
+});
170
+
171
+const toolkits = await session.toolkits();
172
+
173
+const pending = requiredToolkits.filter((slug) => {
174
+ const toolkit = toolkits.find((t) => t.slug === slug);
175
+ return !toolkit?.connectedAccount;
176
+});
177
+
178
+if (pending.length > 0) {
179
+ for (const slug of pending) {
180
+ const connectionRequest = await session.authorize(slug, {
181
+ callbackUrl: "https://yourapp.com/onboarding",
182
+ });
183
+ // Show connectionRequest.redirectUrl to user
184
+ }
185
+ // Wait for all connections before continuing
186
+}
187
+
188
+// All apps connected, start the agent
189
+const tools = await session.tools();
190
+```
191
+</CodeGroup>
192
+
193
+## Multiple accounts
194
+
195
+Users can connect multiple accounts for the same toolkit (e.g., personal and work Gmail). Tool Router uses the most recently connected account by default.
196
+
197
+To use a specific account, pass it in the session config:
198
+
199
+<CodeGroup>
200
+```python
201
+session = await composio.create_session(
202
+ user=user_id,
203
+ connected_accounts={
204
+ "gmail": "ca_specific_account_id",
205
+ },
206
+)
207
+```
208
+```typescript
209
+const session = await composio.createSession({
210
+ user: userId,
211
+ connectedAccounts: {
212
+ gmail: "ca_specific_account_id",
213
+ },
214
+});
215
+```
216
+</CodeGroup>
217
+
218
+## Full example
219
+
220
+<CodeGroup>
221
+<CodeGroupItem title="Python">
222
+<SnippetCode src="fern/snippets/tool-router/python/manual-auth.py" />
223
+</CodeGroupItem>
224
+<CodeGroupItem title="TypeScript">
225
+<SnippetCode src="fern/snippets/tool-router/typescript/manual-auth.ts" />
226
+</CodeGroupItem>
227
+</CodeGroup>
228
+
fern/pages/src/tool-router/using-in-chat-authentication.mdx
+31
-12
@@ -9,61 +9,80 @@ In-chat authentication lets your agent prompt users to connect accounts during c
9
10
## How it works
11
12
-1. User asks agent to do something (e.g., "star my repos")
13
-2. Agent tries to execute but user hasn't connected GitHub
14
-3. `COMPOSIO_MANAGE_CONNECTIONS` returns a Connect Link URL
15
-4. Agent shares the URL with the user
16
-5. User clicks, authenticates, returns to chat
17
-6. User confirms ("done") and agent retries successfully
12
+1. Agent searches for tools via `COMPOSIO_SEARCH_TOOLS`
13
+2. `COMPOSIO_MANAGE_CONNECTIONS` checks connection status, returns Connect Link URL if needed
14
+3. User authenticates, confirms in chat, agent continues
15
16
## Configuration
17
18
In-chat auth is enabled by default. The `COMPOSIO_MANAGE_CONNECTIONS` meta-tool is included automatically.
19
20
+<CodeGroup>
21
+```python
22
+session = await composio.create_session(
23
+ user="pg-user-550e8400-e29b-41d4",
24
+)
25
+```
26
```typescript
27
const session = await composio.createSession({
28
user: "pg-user-550e8400-e29b-41d4",
26
- toolkits: ["github", "gmail"],
29
});
30
```
31
+</CodeGroup>
32
33
### Custom callback URL
34
35
Redirect users to a specific page after authentication:
36
37
+<CodeGroup>
38
+```python
39
+session = await composio.create_session(
40
+ user="pg-user-550e8400-e29b-41d4",
41
+ manage_connections={
42
+ "callback_url": "https://yourapp.com/chat"
43
+ },
44
+)
45
+```
46
```typescript
47
const session = await composio.createSession({
48
user: "pg-user-550e8400-e29b-41d4",
37
- toolkits: ["github", "gmail"],
49
manageConnections: {
50
callbackUrl: "https://yourapp.com/chat",
51
},
52
});
53
```
54
+</CodeGroup>
55
56
### Disabling in-chat auth
57
58
To manage authentication outside of chat, disable the `COMPOSIO_MANAGE_CONNECTIONS` tool:
59
60
+<CodeGroup>
61
+```python
62
+session = await composio.create_session(
63
+ user="pg-user-550e8400-e29b-41d4",
64
+ manage_connections=False,
65
+)
66
+```
67
```typescript
68
const session = await composio.createSession({
69
user: "pg-user-550e8400-e29b-41d4",
51
- toolkits: ["github", "gmail"],
70
manageConnections: false,
71
});
72
```
73
+</CodeGroup>
74
75
See [Manually authenticating users](/tool-router/manually-authenticating-users) for the alternative approach.
76
77
## Examples
78
79
<CodeGroup>
61
-<CodeGroupItem title="Vercel AI SDK (TypeScript)">
62
-<SnippetCode src="fern/snippets/tool-router/typescript/in-chat-auth.ts" />
63
-</CodeGroupItem>
80
<CodeGroupItem title="OpenAI Agents SDK (Python)">
81
<SnippetCode src="fern/snippets/tool-router/python/in-chat-auth.py" />
82
</CodeGroupItem>
83
+<CodeGroupItem title="Vercel AI SDK (TypeScript)">
84
+<SnippetCode src="fern/snippets/tool-router/typescript/in-chat-auth.ts" />
85
+</CodeGroupItem>
86
</CodeGroup>
87
88
### Example conversation
fern/snippets/tool-router/python/manual-auth.py
new
+43
@@ -0,0 +1,43 @@
1
+import asyncio
2
+from composio import Composio
3
+
4
+composio = Composio()
5
+
6
+user_id = "pg-user-550e8400-e29b-41d4"
7
+required_toolkits = ["gmail", "googlecalendar", "linear", "slack"]
8
+
9
+async def main():
10
+ session = await composio.create_session(
11
+ user=user_id,
12
+ manage_connections=False,
13
+ )
14
+
15
+ toolkits = await session.toolkits()
16
+
17
+ def is_connected(slug):
18
+ toolkit = next((t for t in toolkits if t.slug == slug), None)
19
+ return toolkit and toolkit.connected_account
20
+
21
+ pending = [slug for slug in required_toolkits if not is_connected(slug)]
22
+
23
+ if pending:
24
+ print("Connect these apps to continue:")
25
+
26
+ for slug in pending:
27
+ connection_request = await session.authorize(
28
+ slug,
29
+ callback_url="https://yourapp.com/onboarding"
30
+ )
31
+ print(f" {slug}: {connection_request.redirect_url}")
32
+
33
+ print("\nWaiting for connections...")
34
+
35
+ for slug in pending:
36
+ connection_request = await session.authorize(slug)
37
+ await connection_request.wait_for_connection(60000)
38
+ print(f" {slug} connected")
39
+
40
+ print("\nAll apps connected. Starting assistant...")
41
+ tools = await session.tools()
42
+
43
+asyncio.run(main())
fern/snippets/tool-router/typescript/manual-auth.ts
new
+47
@@ -0,0 +1,47 @@
1
+import { Composio } from "@composio/core";
2
+import { VercelProvider } from "@composio/vercel";
3
+
4
+const composio = new Composio({
5
+ provider: new VercelProvider(),
6
+});
7
+
8
+const userId = "pg-user-550e8400-e29b-41d4";
9
+const requiredToolkits = ["gmail", "googlecalendar", "linear", "slack"];
10
+
11
+async function main() {
12
+ const session = await composio.createSession({
13
+ user: userId,
14
+ manageConnections: false,
15
+ });
16
+
17
+ const toolkits = await session.toolkits();
18
+
19
+ const pending = requiredToolkits.filter((slug) => {
20
+ const toolkit = toolkits.find((t) => t.slug === slug);
21
+ return !toolkit?.connectedAccount;
22
+ });
23
+
24
+ if (pending.length > 0) {
25
+ console.log("Connect these apps to continue:");
26
+
27
+ for (const slug of pending) {
28
+ const connectionRequest = await session.authorize(slug, {
29
+ callbackUrl: "https://yourapp.com/onboarding",
30
+ });
31
+ console.log(` ${slug}: ${connectionRequest.redirectUrl}`);
32
+ }
33
+
34
+ console.log("\nWaiting for connections...");
35
+
36
+ for (const slug of pending) {
37
+ const connectionRequest = await session.authorize(slug);
38
+ await connectionRequest.waitForConnection(60000);
39
+ console.log(` ${slug} connected`);
40
+ }
41
+ }
42
+
43
+ console.log("\nAll apps connected. Starting assistant...");
44
+ const tools = await session.tools();
45
+}
46
+
47
+main();