Skip to content

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

Sushmithamallesh6082f003839a
diff --git a/fern/pages/src/tool-router/manually-authenticating-users.mdx b/fern/pages/src/tool-router/manually-authenticating-users.mdx
index 56dbab1f4..1184ad53e 100644
--- a/fern/pages/src/tool-router/manually-authenticating-users.mdx
+++ b/fern/pages/src/tool-router/manually-authenticating-users.mdx
@@ -1,7 +1,228 @@
---
-title: Manually Authenticating Users
+title: Manually authenticating users
image: "https://og.composio.dev/api/og?title=Manually%20Authenticating%20Users"
-description: "Programmatically authenticate users to toolkits"
-keywords: "tool router"
+description: "Authenticate users to toolkits outside of chat"
+keywords: "tool router, authentication, manual, authorize, toolkits"
---
+Manual authentication lets you connect users to toolkits outside of the chat flow. Use this when you want to:
+- Pre-authenticate users before they start chatting
+- Build a custom connections UI in your app
+
+## Create session
+
+Disable the `COMPOSIO_MANAGE_CONNECTIONS` meta-tool so the agent doesn't prompt for auth during chat:
+
+<CodeGroup>
+```python
+session = await composio.create_session(
+ user="pg-user-550e8400-e29b-41d4",
+ manage_connections=False,
+)
+```
+```typescript
+const session = await composio.createSession({
+ user: "pg-user-550e8400-e29b-41d4",
+ manageConnections: false,
+});
+```
+</CodeGroup>
+
+## Check connection status
+
+Use `session.toolkits()` to see which apps the user has connected:
+
+<CodeGroup>
+```python
+toolkits = await session.toolkits()
+
+for toolkit in toolkits:
+ status = toolkit.connected_account.status if toolkit.connected_account else "Not connected"
+ print(f"{toolkit.name}: {status}")
+```
+```typescript
+const toolkits = await session.toolkits();
+
+for (const toolkit of toolkits) {
+ const status = toolkit.connectedAccount?.status || "Not connected";
+ console.log(`${toolkit.name}: ${status}`);
+}
+```
+</CodeGroup>
+
+Each toolkit includes:
+- `name`, `slug`, `logo`, `description`
+- `connectedAccount` - present if user is connected, includes `id`, `status`, `createdAt`
+
+### Filter and sort
+
+Use filters to show relevant toolkits in your UI:
+
+<CodeGroup>
+```python
+toolkits = await session.toolkits(
+ order_by="popularity", # Sort by most used
+ order_direction="desc",
+ category="developer-tools", # Filter by category
+ is_connected=True, # Only show connected apps
+)
+```
+```typescript
+const toolkits = await session.toolkits({
+ orderBy: "popularity", // Sort by most used
+ orderDirection: "desc",
+ category: "developer-tools", // Filter by category
+ isConnected: true, // Only show connected apps
+});
+```
+</CodeGroup>
+
+## Generate auth URL
+
+Use `session.authorize()` to generate a [Connect Link](/docs/authenticating-tools#hosted-authentication-connect-link) URL:
+
+<CodeGroup>
+```python
+connection_request = await session.authorize(
+ "gmail",
+ callback_url="https://yourapp.com/callback"
+)
+
+print(connection_request.redirect_url)
+# https://connect.composio.dev/link/ln_abc123
+```
+```typescript
+const connectionRequest = await session.authorize("gmail", {
+ callbackUrl: "https://yourapp.com/callback",
+});
+
+console.log(connectionRequest.redirectUrl);
+// https://connect.composio.dev/link/ln_abc123
+```
+</CodeGroup>
+
+Redirect the user to `redirectUrl`. After they authenticate, they'll be redirected to your `callbackUrl`.
+
+## Wait for connection
+
+Use `waitForConnection()` to poll until the user completes authentication:
+
+<CodeGroup>
+```python
+connected_account = await connection_request.wait_for_connection(60000)
+print(f"Connected: {connected_account.id}")
+```
+```typescript
+const connectedAccount = await connectionRequest.waitForConnection(60000);
+console.log(`Connected: ${connectedAccount.id}`);
+```
+</CodeGroup>
+
+- Default timeout: 60 seconds (60000ms)
+- Throws `ConnectionRequestTimeoutError` if timeout expires
+- Throws `ConnectionRequestFailedError` if connection fails or expires
+
+<Note>
+If the user closes the Connect Link without completing auth, the connection remains in `INITIATED` status until it expires.
+</Note>
+
+## Putting it together
+
+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:
+
+<CodeGroup>
+```python
+required_toolkits = ["gmail", "googlecalendar", "linear", "slack"]
+
+session = await composio.create_session(
+ user=user_id,
+ manage_connections=False,
+)
+
+toolkits = await session.toolkits()
+
+def is_connected(slug):
+ toolkit = next((t for t in toolkits if t.slug == slug), None)
+ return toolkit and toolkit.connected_account
+
+pending = [slug for slug in required_toolkits if not is_connected(slug)]
+
+if pending:
+ for slug in pending:
+ connection_request = await session.authorize(
+ slug,
+ callback_url="https://yourapp.com/onboarding"
+ )
+ # Show connection_request.redirect_url to user
+
+ # Wait for all connections before continuing
+
+# All apps connected, start the agent
+tools = await session.tools()
+```
+```typescript
+const requiredToolkits = ["gmail", "googlecalendar", "linear", "slack"];
+
+const session = await composio.createSession({
+ user: userId,
+ manageConnections: false,
+});
+
+const toolkits = await session.toolkits();
+
+const pending = requiredToolkits.filter((slug) => {
+ const toolkit = toolkits.find((t) => t.slug === slug);
+ return !toolkit?.connectedAccount;
+});
+
+if (pending.length > 0) {
+ for (const slug of pending) {
+ const connectionRequest = await session.authorize(slug, {
+ callbackUrl: "https://yourapp.com/onboarding",
+ });
+ // Show connectionRequest.redirectUrl to user
+ }
+ // Wait for all connections before continuing
+}
+
+// All apps connected, start the agent
+const tools = await session.tools();
+```
+</CodeGroup>
+
+## Multiple accounts
+
+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.
+
+To use a specific account, pass it in the session config:
+
+<CodeGroup>
+```python
+session = await composio.create_session(
+ user=user_id,
+ connected_accounts={
+ "gmail": "ca_specific_account_id",
+ },
+)
+```
+```typescript
+const session = await composio.createSession({
+ user: userId,
+ connectedAccounts: {
+ gmail: "ca_specific_account_id",
+ },
+});
+```
+</CodeGroup>
+
+## Full example
+
+<CodeGroup>
+<CodeGroupItem title="Python">
+<SnippetCode src="fern/snippets/tool-router/python/manual-auth.py" />
+</CodeGroupItem>
+<CodeGroupItem title="TypeScript">
+<SnippetCode src="fern/snippets/tool-router/typescript/manual-auth.ts" />
+</CodeGroupItem>
+</CodeGroup>
+
diff --git a/fern/pages/src/tool-router/using-in-chat-authentication.mdx b/fern/pages/src/tool-router/using-in-chat-authentication.mdx
index a8bc5218f..5dd42e91a 100644
--- a/fern/pages/src/tool-router/using-in-chat-authentication.mdx
+++ b/fern/pages/src/tool-router/using-in-chat-authentication.mdx
@@ -9,61 +9,80 @@ In-chat authentication lets your agent prompt users to connect accounts during c
## How it works
-1. User asks agent to do something (e.g., "star my repos")
-2. Agent tries to execute but user hasn't connected GitHub
-3. `COMPOSIO_MANAGE_CONNECTIONS` returns a Connect Link URL
-4. Agent shares the URL with the user
-5. User clicks, authenticates, returns to chat
-6. User confirms ("done") and agent retries successfully
+1. Agent searches for tools via `COMPOSIO_SEARCH_TOOLS`
+2. `COMPOSIO_MANAGE_CONNECTIONS` checks connection status, returns Connect Link URL if needed
+3. User authenticates, confirms in chat, agent continues
## Configuration
In-chat auth is enabled by default. The `COMPOSIO_MANAGE_CONNECTIONS` meta-tool is included automatically.
+<CodeGroup>
+```python
+session = await composio.create_session(
+ user="pg-user-550e8400-e29b-41d4",
+)
+```
```typescript
const session = await composio.createSession({
user: "pg-user-550e8400-e29b-41d4",
- toolkits: ["github", "gmail"],
});
```
+</CodeGroup>
### Custom callback URL
Redirect users to a specific page after authentication:
+<CodeGroup>
+```python
+session = await composio.create_session(
+ user="pg-user-550e8400-e29b-41d4",
+ manage_connections={
+ "callback_url": "https://yourapp.com/chat"
+ },
+)
+```
```typescript
const session = await composio.createSession({
user: "pg-user-550e8400-e29b-41d4",
- toolkits: ["github", "gmail"],
manageConnections: {
callbackUrl: "https://yourapp.com/chat",
},
});
```
+</CodeGroup>
### Disabling in-chat auth
To manage authentication outside of chat, disable the `COMPOSIO_MANAGE_CONNECTIONS` tool:
+<CodeGroup>
+```python
+session = await composio.create_session(
+ user="pg-user-550e8400-e29b-41d4",
+ manage_connections=False,
+)
+```
```typescript
const session = await composio.createSession({
user: "pg-user-550e8400-e29b-41d4",
- toolkits: ["github", "gmail"],
manageConnections: false,
});
```
+</CodeGroup>
See [Manually authenticating users](/tool-router/manually-authenticating-users) for the alternative approach.
## Examples
<CodeGroup>
-<CodeGroupItem title="Vercel AI SDK (TypeScript)">
-<SnippetCode src="fern/snippets/tool-router/typescript/in-chat-auth.ts" />
-</CodeGroupItem>
<CodeGroupItem title="OpenAI Agents SDK (Python)">
<SnippetCode src="fern/snippets/tool-router/python/in-chat-auth.py" />
</CodeGroupItem>
+<CodeGroupItem title="Vercel AI SDK (TypeScript)">
+<SnippetCode src="fern/snippets/tool-router/typescript/in-chat-auth.ts" />
+</CodeGroupItem>
</CodeGroup>
### Example conversation
diff --git a/fern/snippets/tool-router/python/manual-auth.py b/fern/snippets/tool-router/python/manual-auth.py
new file mode 100644
index 000000000..16653be18
--- /dev/null
+++ b/fern/snippets/tool-router/python/manual-auth.py
@@ -0,0 +1,43 @@
+import asyncio
+from composio import Composio
+
+composio = Composio()
+
+user_id = "pg-user-550e8400-e29b-41d4"
+required_toolkits = ["gmail", "googlecalendar", "linear", "slack"]
+
+async def main():
+ session = await composio.create_session(
+ user=user_id,
+ manage_connections=False,
+ )
+
+ toolkits = await session.toolkits()
+
+ def is_connected(slug):
+ toolkit = next((t for t in toolkits if t.slug == slug), None)
+ return toolkit and toolkit.connected_account
+
+ pending = [slug for slug in required_toolkits if not is_connected(slug)]
+
+ if pending:
+ print("Connect these apps to continue:")
+
+ for slug in pending:
+ connection_request = await session.authorize(
+ slug,
+ callback_url="https://yourapp.com/onboarding"
+ )
+ print(f" {slug}: {connection_request.redirect_url}")
+
+ print("\nWaiting for connections...")
+
+ for slug in pending:
+ connection_request = await session.authorize(slug)
+ await connection_request.wait_for_connection(60000)
+ print(f" {slug} connected")
+
+ print("\nAll apps connected. Starting assistant...")
+ tools = await session.tools()
+
+asyncio.run(main())
diff --git a/fern/snippets/tool-router/typescript/manual-auth.ts b/fern/snippets/tool-router/typescript/manual-auth.ts
new file mode 100644
index 000000000..859ffafa5
--- /dev/null
+++ b/fern/snippets/tool-router/typescript/manual-auth.ts
@@ -0,0 +1,47 @@
+import { Composio } from "@composio/core";
+import { VercelProvider } from "@composio/vercel";
+
+const composio = new Composio({
+ provider: new VercelProvider(),
+});
+
+const userId = "pg-user-550e8400-e29b-41d4";
+const requiredToolkits = ["gmail", "googlecalendar", "linear", "slack"];
+
+async function main() {
+ const session = await composio.createSession({
+ user: userId,
+ manageConnections: false,
+ });
+
+ const toolkits = await session.toolkits();
+
+ const pending = requiredToolkits.filter((slug) => {
+ const toolkit = toolkits.find((t) => t.slug === slug);
+ return !toolkit?.connectedAccount;
+ });
+
+ if (pending.length > 0) {
+ console.log("Connect these apps to continue:");
+
+ for (const slug of pending) {
+ const connectionRequest = await session.authorize(slug, {
+ callbackUrl: "https://yourapp.com/onboarding",
+ });
+ console.log(` ${slug}: ${connectionRequest.redirectUrl}`);
+ }
+
+ console.log("\nWaiting for connections...");
+
+ for (const slug of pending) {
+ const connectionRequest = await session.authorize(slug);
+ await connectionRequest.waitForConnection(60000);
+ console.log(` ${slug} connected`);
+ }
+ }
+
+ console.log("\nAll apps connected. Starting assistant...");
+ const tools = await session.tools();
+}
+
+main();