Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
authentication concept doc
Sushmithamallesh committed
Nov 30, 2025 at 00:00 UTC
ae0fac3f3a34bd6033dcd0687372dd40a9c2237b
1 file changed
+53
-2
fern/pages/src/tool-router/authentication.mdx
+53
-2
@@ -1,7 +1,58 @@
1
---
2
title: Authentication
3
image: "https://og.composio.dev/api/og?title=Authentication"
4
-description: "Authenticate users to toolkits with MANAGE_CONNECTIONS_TOOL"
5
-keywords: "tool router"
4
+description: "Understand how Tool Router handles user authentication to toolkits"
5
+keywords: "authentication, tool router, oauth, api key, connected accounts"
6
+hide-nav-links: false
7
---
8
9
+Tool Router automatically generates [Connect Link](/docs/authenticating-tools#hosted-authentication-connect-link) URLs when tools require authentication. Users complete OAuth or enter credentials on this hosted page.
10
+
11
+## In-chat authentication
12
+
13
+By default, Tool Router includes the `COMPOSIO_MANAGE_CONNECTIONS` meta-tool. When the agent tries to execute a tool and the user hasn't connected that account, the agent prompts them with a Connect Link URL.
14
+
15
+The user clicks the link, authenticates in the hosted UI, and confirms in chat. The agent then retries the action.
16
+
17
+This flow works well for chat applications where users interact directly with the agent. For details on configuring this flow, see [Using in-chat authentication](/tool-router/using-in-chat-authentication).
18
+
19
+## Manual authentication
20
+
21
+For applications that manage authentication outside of chat, disable in-chat auth and use `session.authorize()` to generate Connect Link URLs.
22
+
23
+This flow works well for:
24
+- Pre-authenticating users before they start chatting
25
+- Building custom connection UIs
26
+
27
+For implementation details, see [Manually authenticating users](/tool-router/manually-authenticating-users).
28
+
29
+## How Tool Router manages auth configs
30
+
31
+When executing a tool, Tool Router needs an auth config to find or create a connected account. It handles this automatically:
32
+
33
+1. If you provide an `authConfigs` override, it uses that
34
+2. Otherwise, it looks for an auth config it previously created for this toolkit
35
+3. If none exists, it creates one using Composio managed auth and tags it for reuse
36
+4. Future sessions automatically reuse that auth config
37
+
38
+This means you don't need to create auth configs manually for most toolkits. Tool Router creates and manages them for you.
39
+
40
+## Supported auth methods
41
+
42
+Tool Router can automatically create auth configs for:
43
+
44
+- **Composio managed OAuth** - GitHub, Gmail, Slack, and most OAuth toolkits. Composio provides the OAuth credentials.
45
+- **API key auth** - Users provide their own API keys via Connect Link.
46
+
47
+<Note>
48
+Toolkits without Composio managed auth require you to [create an auth config](/docs/authenticating-tools#creating-an-auth-config) first and pass it via `authConfigs`.
49
+</Note>
50
+
51
+## White-labeling
52
+
53
+To show your own branding on OAuth consent screens instead of Composio's, create your own OAuth app and pass the auth config ID in your session. See [White-labeling authentication](/tool-router/white-labeling-authentication).
54
+
55
+<Tip>
56
+For step-by-step guides on creating OAuth apps for specific services, see [composio.dev/auth](https://composio.dev/auth).
57
+</Tip>
58
+