Authenticate Users with Composio Connect Links

Composio provides two authentication flows for connecting users to third-party apps. In-chat authentication lets the agent handle OAuth prompts automatically — no extra setup required. Manual authentication lets your app initiate connections during onboarding or from a settings page, giving you full control over when and where users authenticate.

In-chat authentication

By default, every session includes the COMPOSIO_MANAGE_CONNECTIONS meta-tool. When a user asks the agent to do something that requires an account the agent hasn’t connected yet, the agent calls this meta-tool and returns a Connect Link URL directly in chat. The user clicks the link, completes OAuth, confirms in the conversation, and the agent retries the original task. No extra setup is required. Just create a session:

Tab Title
Tab Title

import { Composio } from "@composio/core";

const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
const session = await composio.create("user_123");
const tools = await session.tools();

from composio import Composio

composio = Composio(api_key="your_api_key")
session = composio.create(user_id="user_123")
tools = session.tools()

When the user triggers a tool that requires authentication, the agent response looks like this:

You: Summarize my emails from today

Agent: I need you to connect your Gmail account first. Please click here to authorize:
       https://connect.composio.dev/link/ln_abc123

You: Done

Agent: Here's a summary of your emails from today...

You can redirect users back to your chat page after they authenticate by passing a callbackUrl:

Tab Title
Tab Title

const session = await composio.create("user_123", {
  manageConnections: {
    callbackUrl: "https://yourapp.com/chat",
  },
});

session = composio.create(
    user_id="user_123",
    manage_connections={
        "callback_url": "https://yourapp.com/chat"
    },
)

Manual authentication with `session.authorize()`

Use manual authentication when you want users connected before they ever start chatting — for example, during onboarding, from a settings page, or as a pre-flight check before running an automated task.

Create a session and disable in-chat auth promptsPass manageConnections: false to prevent the agent from prompting users to authenticate in chat. You’ll handle auth entirely in your UI.

Tab Title
Tab Title

const session = await composio.create("user_123", {
  manageConnections: false,
});

session = composio.create(
    user_id="user_123",
    manage_connections=False,
)

Generate a Connect Link with session.authorize()Call session.authorize() with the toolkit slug to get a redirectUrl (also called redirect_url in Python). Redirect the user to this URL to start the OAuth flow.

Tab Title
Tab Title

const connectionRequest = await session.authorize("gmail");

console.log(connectionRequest.redirectUrl);
// https://connect.composio.dev/link/ln_abc123

// Redirect the user to this URL in your UI

connection_request = session.authorize("gmail")

print(connection_request.redirect_url)
# https://connect.composio.dev/link/ln_abc123

Wait for the user to complete OAuthPoll for completion using waitForConnection() / wait_for_connection(). The method resolves with the connected account once the user finishes authentication.

Tab Title
Tab Title

const connectedAccount = await connectionRequest.waitForConnection(60000);
console.log(`Connected: ${connectedAccount.id}`);

connected_account = connection_request.wait_for_connection(60000)
print(f"Connected: {connected_account.id}")

If the user closes the Connect Link without completing auth, the connection stays in INITIATED status until it expires. waitForConnection() will timeout after the specified milliseconds.

Callback URL

Pass a callbackUrl to control where users land after they finish authenticating. You can embed query parameters to carry context through the OAuth flow:

Tab Title
Tab Title

const connectionRequest = await session.authorize("gmail", {
  callbackUrl: "https://your-app.com/callback?user_id=user_123&source=onboarding",
});

console.log(connectionRequest.redirectUrl);

connection_request = session.authorize(
    "gmail",
    callback_url="https://your-app.com/callback?user_id=user_123&source=onboarding",
)

print(connection_request.redirect_url)

After authentication, Composio redirects the user to your callback URL with these parameters appended:

Parameter	Description
`status`	`success` or `failed`
`connected_account_id`	The ID of the newly created connected account

https://your-app.com/callback?user_id=user_123&source=onboarding&status=success&connected_account_id=ca_abc123

Checking connection status

Use session.toolkits() to inspect which toolkits are connected for the current session user:

Tab Title
Tab Title

const toolkits = await session.toolkits();

toolkits.items.forEach((toolkit) => {
  const accountId = toolkit.connection?.connectedAccount?.id ?? "Not connected";
  console.log(`${toolkit.name}: ${accountId}`);
});

toolkits = session.toolkits()

for toolkit in toolkits.items:
    if toolkit.connection.is_active:
        status = toolkit.connection.connected_account.id
    else:
        status = "Not connected"
    print(f"{toolkit.name}: {status}")

Putting it all together

A common pattern is to verify all required connections before starting the agent loop:

Tab Title
Tab Title

import { Composio } from "@composio/core";

const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
const requiredToolkits = ["gmail", "github"];

const session = await composio.create("user_123", {
  manageConnections: false,
});

const toolkits = await session.toolkits();

const connected = toolkits.items
  .filter((t) => t.connection?.connectedAccount)
  .map((t) => t.slug);

const pending = requiredToolkits.filter((slug) => !connected.includes(slug));

console.log("Connected:", connected);
console.log("Pending:", pending);

for (const slug of pending) {
  const connectionRequest = await session.authorize(slug);
  console.log(`Connect ${slug}: ${connectionRequest.redirectUrl}`);
  await connectionRequest.waitForConnection();
}

console.log(`All toolkits connected! MCP URL: ${session.mcp.url}`);

from composio import Composio

composio = Composio(api_key="your-api-key")
required_toolkits = ["gmail", "github"]

session = composio.create(
    user_id="user_123",
    manage_connections=False,
)

toolkits = session.toolkits()

connected = {t.slug for t in toolkits.items if t.connection.is_active}
pending = [slug for slug in required_toolkits if slug not in connected]

print(f"Connected: {connected}")
print(f"Pending: {pending}")

for slug in pending:
    connection_request = session.authorize(slug)
    print(f"Connect {slug}: {connection_request.redirect_url}")
    connection_request.wait_for_connection()

print(f"All toolkits connected! MCP URL: {session.mcp.url}")

Sessions

Understand how sessions work and what options are available

Connected Accounts

Manage multiple connected accounts per user and toolkit

MCP

Use the session MCP URL with Claude Desktop, Cursor, and other MCP clients

Tool Router

Semantically select tools at runtime to keep LLM context focused

Get Started

Core Concepts

Guides

Providers

CLI

Authenticate Users with Composio Connect Links

In-chat authentication

Manual authentication with `session.authorize()`

Callback URL

Checking connection status

Putting it all together

Sessions

Connected Accounts

MCP

Tool Router

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Providers

CLI

Documentation Index

​In-chat authentication

​Manual authentication with session.authorize()

​Callback URL

​Checking connection status

​Putting it all together

Sessions

Connected Accounts

MCP

Tool Router

Build docs developers (and LLMs) love

In-chat authentication

Manual authentication with `session.authorize()`

Callback URL

Checking connection status

Putting it all together