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

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}`);