Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdxindex 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 usersimage: "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.mdxindex 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## ConfigurationIn-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",+)+``````typescriptconst session = await composio.createSession({user: "pg-user-550e8400-e29b-41d4",- toolkits: ["github", "gmail"],});```+</CodeGroup>### Custom callback URLRedirect 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"+ },+)+``````typescriptconst session = await composio.createSession({user: "pg-user-550e8400-e29b-41d4",- toolkits: ["github", "gmail"],manageConnections: {callbackUrl: "https://yourapp.com/chat",},});```+</CodeGroup>### Disabling in-chat authTo 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,+)+``````typescriptconst 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 conversationdiff --git a/fern/snippets/tool-router/python/manual-auth.py b/fern/snippets/tool-router/python/manual-auth.pynew file mode 100644index 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.tsnew file mode 100644index 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();