@devries-cameron20 / composio Mirror · read-only / commits / ae0fac3f3
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 18:15 UTC

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 +