@devries-cameron20 / composio Mirror · read-only / commits / 6082f0038
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 18:15 UTC

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();