Authentication

Tool Router handles authentication through Connect Links, hosted pages where users complete OAuth or enter credentials.

In-chat authentication

By default, when a tool requires authentication, the agent prompts the user with a Connect Link. The user authenticates and confirms in chat. The agent handles OAuth flows, token refresh, and credential management automatically.

Here’s what this looks like in a conversation:

You: Star the composio repo on GitHub
Agent: I need you to connect your GitHub account first.
       Please click here to authorize: https://connect.composio.dev/link/ln_abc123
You: Done
Agent: Done! I've starred ComposioHQ/composio.

This flow works well for chat applications where users interact directly with the agent. See Using in-chat authentication.

Manual authentication

For apps that manage auth outside of chat, use session.authorize() to generate Connect Links programmatically:

1
connection_request = session.authorize("github")
2
print(connection_request.redirect_url)
3
# https://connect.composio.dev/link/ln_abc123

Use this when you want users to connect accounts during onboarding, or when building a custom connections page. See Manually authenticating users for a detailed guide.

How Tool Router manages auth configs

When executing a tool, Tool Router needs an auth config to find or create a connected account. It handles this automatically:

1. Uses your authConfigs override if provided
2. Otherwise, reuses an auth config it previously created for this toolkit
3. If none exists, creates one using Composio managed auth

You don’t need to create auth configs manually for most toolkits.

Supported auth methods

Tool Router supports Composio managed OAuth (GitHub, Gmail, Slack, and most toolkits) and API key auth (users enter their own keys via Connect Link).

White-labeling

Show your own branding on OAuth consent screens by creating your own OAuth app. See White-labeling authentication.