Skip to content

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

docs: improve authentication page content and structure

Sushmithamallesha6be5a3cb7dd
diff --git a/docs/content/docs/authentication.mdx b/docs/content/docs/authentication.mdx
index 2b162514c..33cf57874 100644
--- a/docs/content/docs/authentication.mdx
+++ b/docs/content/docs/authentication.mdx
@@ -1,10 +1,10 @@
---
title: Authentication
-description: Understand how Tool Router handles user authentication to toolkits
-keywords: [connect link, oauth]
+description: Understand how Composio handles user authentication to toolkits
+keywords: [connect link, oauth, auth config]
---
-Tool Router handles authentication through Connect Links, hosted pages where users complete OAuth or enter credentials.
+Composio simplifies authentication with Connect Links: hosted pages where users securely connect their accounts.
<video src="/images/connect-link-auth-flow-recording.mp4" autoPlay loop muted playsInline className="rounded-lg border" />
@@ -33,44 +33,60 @@ This flow works well for chat applications where users interact directly with th
For apps that manage auth outside of chat, use `session.authorize()` to generate Connect Links programmatically. This is useful when you want users to connect accounts during onboarding, or when building a custom connections page.
<Card icon={<BookOpen />} title="Manual authentication" href="/docs/authenticating-users/manually-authenticating">
- Generate Connect Links and manage authentication flows in your application
+ Control when and how users connect their accounts
</Card>
-## How Tool Router manages auth configs
+## How Composio manages authentication
-When executing a tool, Tool Router needs an auth config to find or create a connected account. It handles this automatically:
+Behind the scenes, Composio uses **auth configs** to manage authentication.
-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
+<Accordions>
+<Accordion title="What is an auth config?">
+An auth config is a blueprint that defines how authentication works for a toolkit across all your users. It defines:
+- **Authentication method** - OAuth2, Bearer token, API key, or Basic Auth
+- **Scopes** - what actions your tools can perform
+- **Credentials** - whether you'll use your own app credentials or Composio's managed auth
+</Accordion>
+</Accordions>
-You don't need to create auth configs manually for most toolkits.
+Composio handles this automatically:
-## Supported auth methods
+1. When a toolkit needs authentication, we create an auth config using Composio managed credentials
+2. The auth config is reused for all users authenticating with that toolkit
+3. Connected accounts are created and linked to your users
-Tool Router supports **Composio managed OAuth** (GitHub, Gmail, Slack, and most toolkits) and **API key auth** (users enter their own keys via Connect Link).
+<Accordions>
+<Accordion title="What are connected accounts?">
+A connected account is created when a user authenticates with a toolkit. It stores the user's credentials (OAuth tokens or API keys) and links them to your user ID. Each user can have multiple connected accounts—even multiple accounts for the same toolkit (e.g., work and personal Gmail).
+</Accordion>
+<Accordion title="What happens when tokens expire?">
+Composio automatically refreshes OAuth tokens before they expire. You don't need to handle re-authentication or token expiration—connected accounts stay valid as long as the user doesn't revoke access.
+</Accordion>
+</Accordions>
-<Callout type="info">
-Toolkits without Composio managed auth require a custom auth config. See [Using custom auth configs](/docs/guides/using-custom-auth-configuration).
-</Callout>
+Most toolkits work out of the box with **Composio managed OAuth**. For API key-based toolkits, users enter their keys directly via Connect Link.
-## White-labeling
+You only need to create a custom auth config when:
+- You want to use your **own OAuth app credentials** for white-labeling
+- You need **specific OAuth scopes** beyond the defaults
+- The toolkit doesn't have Composio managed auth
+- You have **existing auth configs** with connected accounts you want to use
-Show your own branding on OAuth consent screens by creating your own OAuth app.
+To bring your own OAuth apps or customize scopes, see [custom auth configs](/docs/using-custom-auth-configuration).
-## Next steps
+## Useful links
<Cards>
- <Card title="In-chat authentication" href="/docs/authenticating-users/in-chat-authentication">
+ <Card icon={<BookOpen />} title="In-chat authentication" href="/docs/authenticating-users/in-chat-authentication">
Let the agent prompt users to authenticate during conversation
</Card>
- <Card title="Manual authentication" href="/docs/authenticating-users/manually-authenticating">
+ <Card icon={<BookOpen />} title="Manual authentication" href="/docs/authenticating-users/manually-authenticating">
Generate Connect Links programmatically in your app
</Card>
- <Card title="White-labeling" href="/docs/white-labeling-authentication">
+ <Card icon={<Palette />} title="White-labeling" href="/docs/white-labeling-authentication">
Customize OAuth screens with your branding
</Card>
- <Card title="Custom auth configs" href="/docs/using-custom-auth-configuration">
- Use your own OAuth apps with Tool Router
+ <Card icon={<Key />} title="Custom auth configs" href="/docs/using-custom-auth-configuration">
+ Use your own OAuth apps
</Card>
</Cards>