@devries-cameron20 / composio-1 / commits / e842e68e4
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.

docs: merge and group guide content (#3456)

## Summary - Stack this PR on top of #3455 (`docs/love-fixes`). - Rework the former Core Concepts / Getting Started / Guides / Features area into a smaller set of sections: - Build with sessions - Authenticate users - Triggers and webhooks - Direct Tool Execution Guides (Legacy) - Other topics - Move conceptual session pages (`how-composio-works`, users/sessions, tools/toolkits, authentication, workbench, triggers) into the appropriate grouped sections. - Merge duplicated custom-auth content into `Managed vs custom auth` (`/docs/custom-app-vs-managed-app`) and redirect the old `/docs/using-custom-auth-configuration` URL. - Trim repeated OAuth-app setup from white-labeling docs so that page focuses on branding, callback-domain routing, and post-auth redirect UX. - Clean up “What to read next” cards so non-legacy pages no longer point at direct-execution docs and first point to the next item in their section where possible. - Fix the session lifecycle contradiction in `how-composio-works` so it matches the current persisted/reusable session model. ## Checks - `cd docs && bun run lint:links` - `cd docs && bun test tests/static/navigation.test.ts`

Rahul Tarak committed May 19, 2026 at 05:17 UTC e842e68e4b495b0b67f2209ef948ec6fe7073b90
43 files changed +295 -612
docs/components/claude-mock-ui.tsx new
+26
@@ -0,0 +1,26 @@
1 +import type { ReactNode } from 'react';
2 +
3 +type ClaudeMockUIProps = {
4 + children: ReactNode;
5 + title?: string;
6 +};
7 +
8 +export function ClaudeMockUI({ children, title = 'user — ✻ Claude Code — claude' }: ClaudeMockUIProps) {
9 + return (
10 + <div className="not-prose my-6 overflow-hidden rounded-xl border border-[#dedede] bg-[#f6f6f6] shadow-sm">
11 + <div className="flex items-center gap-2 border-[#d8d8d8] border-b bg-[#e8e8e8] px-3 py-2">
12 + <div className="flex items-center gap-1.5" aria-hidden="true">
13 + <span className="h-[11px] w-[11px] rounded-full bg-[#ff5f57]" />
14 + <span className="h-[11px] w-[11px] rounded-full bg-[#febc2e]" />
15 + <span className="h-[11px] w-[11px] rounded-full bg-[#28c840]" />
16 + </div>
17 + <span className="flex-1 truncate text-left font-mono text-[#888] text-[11px]">
18 + {title}
19 + </span>
20 + </div>
21 + <div className="space-y-4 bg-[#f6f6f6] p-5 font-mono text-[13px] text-[#2d2d2d] leading-7 md:text-sm [&_a]:text-[#0000ee] [&_a]:underline [&_a]:underline-offset-2 [&_p]:m-0 [&_strong]:font-semibold [&_strong]:text-[#111]">
22 + {children}
23 + </div>
24 + </div>
25 + );
26 +}
docs/components/quickstart/integration-tabs.tsx
+7 -1
@@ -79,7 +79,13 @@ function PortaledTabsHeader({ tabs }: { tabs: TabConfig[] }) {
79
80 const header = (
81 <div className="mt-4 border-t border-fd-border pt-4">
82 - <p className="mb-3 text-sm font-medium text-fd-muted-foreground">Choose your integration type · <Link href="/docs/native-tools-vs-mcp" className="text-fd-muted-foreground hover:text-fd-foreground transition-colors underline underline-offset-2">Use this guide to decide</Link></p>
82 + <p className="mb-3 max-w-2xl text-sm text-fd-muted-foreground">
83 + If your framework has good native tool-calling support, we recommend native tools. The remote MCP URL is always available too.{' '}
84 + <Link href="/docs/native-tools-vs-mcp" className="text-fd-muted-foreground hover:text-fd-foreground transition-colors underline underline-offset-2">
85 + Learn the differences
86 + </Link>
87 + .
88 + </p>
89 <TabsHeader tabs={tabs} />
90 </div>
91 );
docs/content/changelog/03-23-26-custom-tools-and-toolkits.mdx
+2 -2
@@ -63,7 +63,7 @@ const sendPromoEmail = experimental_createTool("SEND_PROMO_EMAIL", {
63
64 // Custom toolkit — groups related tools under a namespace
65 const userManagement = experimental_createToolkit("USER_MANAGEMENT", {
66 - name: "User management",
66 + name: "User scoping",
67 description: "Manage user roles and permissions",
68 tools: [
69 experimental_createTool("ASSIGN_ROLE", {
@@ -144,7 +144,7 @@ def send_promo_email(input: PromoEmailInput, ctx):
144
145 user_management = composio.experimental.Toolkit(
146 slug="USER_MANAGEMENT",
147 - name="User management",
147 + name="User scoping",
148 description="Manage user roles and permissions",
149 )
150
docs/content/changelog/05-08-26-session-use-update-connected-accounts.mdx
+2 -2
@@ -41,7 +41,7 @@ const tools = await session.tools();
41 </Tab>
42 </Tabs>
43
44 -Custom tools can also be attached when reusing a session. See [Reusing a session](/docs/users-and-sessions#reusing-a-session) and [Custom tools](/docs/toolkits/custom-tools-and-toolkits#reusing-a-session-with-custom-tools).
44 +Custom tools can also be attached when reusing a session. See [Reusing a session](/docs/how-composio-works#how-sessions-behave) and [Custom tools](/docs/toolkits/custom-tools-and-toolkits#reusing-a-session-with-custom-tools).
45
46 ### Update session config with `session.update()`
47
@@ -70,7 +70,7 @@ await session.update({
70 </Tab>
71 </Tabs>
72
73 -See [Updating a session](/docs/users-and-sessions#updating-a-session).
73 +See [Updating a session](/docs/how-composio-works#how-sessions-behave).
74
75 ### `connectedAccounts` accepts arrays
76
docs/content/changelog/11-05-25.mdx
+1 -1
@@ -54,7 +54,7 @@ If you're using an existing project and want to adopt this security enhancement:
54 3. Update your application code to pass the appropriate identifier
55 4. Test the updated URLs in your development environment
56
57 -For more details on choosing the right user identifiers for your application, see our [User Management documentation](/docs/users-and-sessions).
57 +For more details on choosing the right user identifiers for your application, see our [session documentation](/docs/how-composio-works).
58
59 ### Questions?
60
docs/content/cookbooks/app-connections-dashboard.mdx
+1 -1
@@ -39,7 +39,7 @@ Create `app/api/connections/route.ts`. Initialize the Composio client and set `d
39
40 <include meta='no-twoslash title="app/api/connections/route.ts"'>../../examples/app-connections-dashboard/connections-route.ts#setup</include>
41
42 -`"user_123"` is a placeholder. In production, replace it with the authenticated user's ID from your auth system. See [Users & Sessions](/docs/users-and-sessions) for details.
42 +`"user_123"` is a placeholder. In production, replace it with the authenticated user's ID from your auth system. See [What is a session?](/docs/how-composio-works) for details.
43
44 ## List connections
45
docs/content/cookbooks/chat-app.mdx
+1 -1
@@ -121,7 +121,7 @@ Try a few more requests:
121 <Card title="Configuring sessions" href="/docs/configuring-sessions">
122 Lock down which toolkits your agent can access
123 </Card>
124 - <Card title="How Composio works" href="/docs/how-composio-works">
124 + <Card title="What is a session?" href="/docs/how-composio-works">
125 Understand sessions, tool discovery, and execution under the hood
126 </Card>
127 </Cards>
docs/content/docs/auth-configuration/custom-auth-configs.mdx
+1 -1
@@ -6,7 +6,7 @@ llmGuardrails: "direct-execution"
6 ---
7
8 <Callout type="info">
9 -If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. See [Using custom auth configs](/docs/using-custom-auth-configuration) for how to use custom credentials with sessions.
9 +If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. See [Managed vs custom auth](/docs/custom-app-vs-managed-app) for how to use custom credentials with sessions.
10 </Callout>
11
12 Auth configs control how users authenticate with a toolkit. By default, Composio provides managed credentials for many toolkits. You create a custom auth config when the defaults don't fit your needs.
docs/content/docs/authenticating-users/manually-authenticating.mdx
+2 -2
@@ -217,8 +217,8 @@ console.log(`All toolkits connected! MCP URL: ${session.mcp.url}`);
217 ## What to read next
218
219 <Cards>
220 - <Card icon={<LayoutDashboard />} title="Build an App Connections Dashboard" href="/cookbooks/app-connections-dashboard" description="Full working example of a connections page with OAuth and disconnect" />
221 - <Card icon={<MessageCircle />} title="In-chat authentication" href="/docs/authenticating-users/in-chat-authentication" description="Let the agent prompt users to connect accounts during conversation instead" />
220 + <Card icon={<Database />} title="Shared connections" href="/docs/authenticating-users/shared-connections" description="Share connected accounts across users while preserving access controls" />
221 <Card icon={<Palette />} title="White-labeling authentication" href="/docs/white-labeling-authentication" description="Use your own OAuth apps so users see your branding on consent screens" />
222 <Card icon={<Database />} title="Managing multiple accounts" href="/docs/managing-multiple-connected-accounts" description="Handle users with multiple accounts for the same toolkit (e.g., work and personal Gmail)" />
223 + <Card icon={<LayoutDashboard />} title="Build an App Connections Dashboard" href="/cookbooks/app-connections-dashboard" description="Full working example of a connections page with OAuth and disconnect" />
224 </Cards>
docs/content/docs/authenticating-users/shared-connections.mdx
+1 -1
@@ -429,7 +429,7 @@ try {
429 ## What to read next
430
431 <Cards>
432 - <Card icon={<Database />} title="Connected accounts" href="/docs/auth-configuration/connected-accounts" description="Manage and monitor user connections to toolkits" />
432 <Card icon={<Plug />} title="Managing multiple connected accounts" href="/docs/managing-multiple-connected-accounts" description="Pin specific accounts into a session at runtime" />
433 <Card icon={<Wrench />} title="Configuring sessions" href="/docs/configuring-sessions" description="Session config — custom auth configs, pinned connections, multi-account" />
434 + <Card icon={<Key />} title="Authentication overview" href="/docs/authentication" description="How users authenticate and how connected accounts are scoped" />
435 </Cards>
docs/content/docs/authentication.mdx
+9 -16
@@ -19,13 +19,12 @@ Not sure? Start with in-chat. You can add manual auth later.
19
20 By default, when a tool requires authentication, the agent prompts the user with a Connect Link. The user authenticates and confirms in chat. No setup needed. Just create a session and the agent handles OAuth flows, token refresh, and credential management automatically.
21
22 -> **You:** Summarize my emails from today
23 ->
24 -> **Agent:** I need you to connect your Gmail account first. Please click here to authorize: https://connect.composio.dev/link/ln_abc123
25 ->
26 -> **You:** Done
27 ->
28 -> **Agent:** Here's a summary of your emails from today...
22 +<ClaudeMockUI>
23 + <p><strong>You:</strong> Summarize my emails from today</p>
24 + <p><strong>Agent:</strong> I need you to connect your Gmail account first. Please click here to authorize: <a href="https://connect.composio.dev/link/ln_abc123">https://connect.composio.dev/link/ln_abc123</a></p>
25 + <p><strong>You:</strong> Done</p>
26 + <p><strong>Agent:</strong> Here's a summary of your emails from today...</p>
27 +</ClaudeMockUI>
28
29 <Card icon={<MessageCircle />} title="In-chat authentication guide" href="/docs/authenticating-users/in-chat-authentication">
30 Configuration, callback URLs, and full examples
@@ -53,7 +52,7 @@ An **auth config** is a blueprint that defines how authentication works for a to
52 - **Scopes**: what actions your tools can perform
53 - **Credentials**: your own app credentials or Composio's managed auth
54
56 -Composio creates one auth config per toolkit, and it applies to every user who connects that toolkit. When a user authenticates, Composio creates a **connected account** that stores their credentials (OAuth tokens or API keys) and links them to your user ID. When you need to use your own OAuth credentials or customize scopes, you can create [custom auth configs](/docs/using-custom-auth-configuration).
55 +Composio creates one auth config per toolkit, and it applies to every user who connects that toolkit. When a user authenticates, Composio creates a **connected account** that stores their credentials (OAuth tokens or API keys) and links them to your user ID. When you need to use your own OAuth credentials or customize scopes, you can create [custom auth configs](/docs/custom-app-vs-managed-app).
56
57 ```mermaid
58 graph LR
@@ -96,19 +95,13 @@ You only need to create a custom auth config when:
95 - The toolkit doesn't have Composio managed auth
96 - You have **existing auth configs** with connected accounts you want to use
97
99 -To bring your own OAuth apps or customize scopes, see [custom auth configs](/docs/using-custom-auth-configuration).
98 +To bring your own OAuth apps or customize scopes, see [custom auth configs](/docs/custom-app-vs-managed-app).
99
100 ## What to read next
101
102 <Cards>
104 - <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="How meta tools discover, authenticate, and execute tools" />
103 <Card icon={<MessageCircle />} title="In-chat authentication" href="/docs/authenticating-users/in-chat-authentication" description="Let the agent prompt users to authenticate during conversation" />
104 <Card icon={<ShieldCheck />} title="Manual authentication" href="/docs/authenticating-users/manually-authenticating" description="Generate Connect Links programmatically in your app" />
107 -</Cards>
108 -
109 -### Related guides
110 -
111 -<Cards>
105 + <Card icon={<Key />} title="Managed vs custom auth" href="/docs/custom-app-vs-managed-app" description="Decide when to use Composio managed auth or your own credentials" />
106 <Card icon={<Palette />} title="White-labeling" href="/docs/white-labeling-authentication" description="Customize OAuth screens with your branding" />
113 - <Card icon={<Key />} title="Custom auth configs" href="/docs/using-custom-auth-configuration" description="Use your own OAuth apps" />
107 </Cards>
docs/content/docs/common-faq.mdx
+9 -9
@@ -9,9 +9,9 @@ keywords: [faq, questions, help, common questions]
9 <Accordions>
10
11 <Accordion title="Do I need an AI agent to use Composio?">
12 -No. If you're building an AI agent, Composio can give it [meta tools](/docs/quickstart) that handle tool discovery and execution automatically, or you can [fetch specific tools](/docs/tools-direct/fetching-tools) and pass them to your agent directly.
12 +No. If you're building an AI agent, Composio can give it [meta tools](/docs/tools-and-toolkits) that handle tool discovery and execution automatically.
13
14 -If you don't have an agent, you can [execute tools directly](/docs/tools-direct/executing-tools#direct-tool-execution) from any backend.
14 +If you don't have an agent, use the legacy direct execution guides under **Direct Tool Execution Guides (Legacy)**.
15 </Accordion>
16
17 <Accordion title="What is the difference between a tool and a toolkit?">
@@ -23,7 +23,7 @@ You connect to toolkits (via OAuth or API keys), and then execute individual too
23 <Accordion title="What is User ID and how should I use it?">
24 The User ID is how Composio identifies your end users. It maps each user to their connected accounts and sessions. Use any unique identifier from your system, like an email, database ID, or UUID.
25
26 -When you create a session with `composio.create(user_id="user_123")`, all connected accounts and tool executions are scoped to that user. See [Users and sessions](/docs/users-and-sessions).
26 +When you create a session with `composio.create(user_id="user_123")`, all connected accounts and tool executions are scoped to that user. See [What is a session?](/docs/how-composio-works).
27 </Accordion>
28
29 <Accordion title="What is the difference between an auth config and an MCP config in the dashboard?">
@@ -39,7 +39,7 @@ See [Native Tools vs MCP](/docs/native-tools-vs-mcp) for a full comparison.
39 </Accordion>
40
41 <Accordion title="When should I create a new session?">
42 -Create a new session when the config changes: different toolkits, different auth config, or a different connected account. You don't need to store or manage session IDs. Just call `create()` each time. See [Users and sessions](/docs/users-and-sessions).
42 +Create a new session when the config changes: different toolkits, different auth config, or a different connected account. You don't need to store or manage session IDs. Just call `create()` each time. See [What is a session?](/docs/how-composio-works).
43 </Accordion>
44
45 </Accordions>
@@ -126,13 +126,13 @@ An auth config is a blueprint that defines how authentication works for a toolki
126
127 If you're using sessions with meta tools (`composio.create()`), you don't need to create auth configs yourself. When a user connects to a toolkit, Composio automatically uses a default auth config with managed credentials. The agent handles the entire flow through `COMPOSIO_MANAGE_CONNECTIONS`.
128
129 -You only need to create auth configs manually when you're [executing tools directly](/docs/tools-direct/authenticating-tools), want to [use your own OAuth app](/docs/white-labeling-authentication), need [custom scopes](/docs/auth-configuration/custom-auth-configs), or are working with a toolkit that doesn't have Composio-managed auth. See [Authentication](/docs/authentication) for the full overview and [When to use your own developer credentials](/docs/custom-app-vs-managed-app) for help deciding.
129 +You only need to create auth configs manually when you're [executing tools directly](/docs/tools-direct/authenticating-tools), want to [use your own OAuth app](/docs/white-labeling-authentication), need [custom scopes](/docs/auth-configuration/custom-auth-configs), or are working with a toolkit that doesn't have Composio-managed auth. See [Authentication](/docs/authentication) for the full overview and [Managed vs custom auth](/docs/custom-app-vs-managed-app) for help deciding.
130 </Accordion>
131
132 <Accordion title="What authentication types does Composio support?">
133 Composio supports **OAuth2**, **OAuth1**, **API Key**, **Bearer Token**, and **Basic Auth**. Most toolkits use OAuth2. Each toolkit defines which auth types it supports. You can see the available schemes when creating an auth config in the dashboard.
134
135 -For toolkits with Composio-managed auth, you don't need to configure anything. For toolkits without it, you'll need to create a [custom auth config](/docs/using-custom-auth-configuration). See [Authentication](/docs/authentication) for the full overview.
135 +For toolkits with Composio-managed auth, you don't need to configure anything. For toolkits without it, you'll need to create a [custom auth config](/docs/custom-app-vs-managed-app). See [Authentication](/docs/authentication) for the full overview.
136 </Accordion>
137
138 <Accordion title="Can a user connect multiple accounts for the same app?">
@@ -189,11 +189,11 @@ Each user gets their own connected account scoped to their `user_id`, but they a
189 </Accordion>
190
191 <Accordion title="How do I configure sessions with custom auth configs?">
192 -Some toolkits require your own OAuth credentials or API keys. Create an auth config in the dashboard by selecting the toolkit, choosing the auth scheme, and entering your credentials. Then pass the auth config ID when creating a session using the `auth_configs` (or `auth_config_id`) parameter so the session uses your developer credentials instead of Composio-managed auth. See [Using custom auth configuration](/docs/using-custom-auth-configuration).
192 +Some toolkits require your own OAuth credentials or API keys. Create an auth config in the dashboard by selecting the toolkit, choosing the auth scheme, and entering your credentials. Then pass the auth config ID when creating a session using the `auth_configs` (or `auth_config_id`) parameter so the session uses your developer credentials instead of Composio-managed auth. See [Managed vs custom auth](/docs/custom-app-vs-managed-app).
193 </Accordion>
194
195 <Accordion title="When should I use my own developer credentials instead of Composio managed auth?">
196 -Use your own credentials when you're going to production and users will see OAuth consent screens, when you need custom scopes, when you're hitting shared rate limits, or when connecting to a self-hosted instance. For development and prototyping, Composio managed auth works out of the box with no setup. See [When to use your own developer credentials](/docs/custom-app-vs-managed-app).
196 +Use your own credentials when you're going to production and users will see OAuth consent screens, when you need custom scopes, when you're hitting shared rate limits, or when connecting to a self-hosted instance. For development and prototyping, Composio managed auth works out of the box with no setup. See [Managed vs custom auth](/docs/custom-app-vs-managed-app).
197 </Accordion>
198
199 <Accordion title="How do I check if a toolkit has Composio managed auth?">
@@ -245,7 +245,7 @@ Yes. White labeling works on all plans, including free. You can create custom au
245 </Accordion>
246
247 <Accordion title="How do I hide the Composio logo during authentication?">
248 -Go to your [project settings](https://platform.composio.dev/settings) and upload your own logo and app title. This replaces Composio branding on the Connect Link page. To also remove "Composio" from OAuth consent screens (Google, GitHub, Slack, etc.), create a custom auth config with your own OAuth credentials. See [White-labeling authentication](/docs/white-labeling-authentication) for the full guide.
248 +Go to your [auth screen settings](https://dashboard.composio.dev/~/project/settings/auth-screen) and upload your own logo and app title. This replaces Composio branding on the Connect Link page. To also remove "Composio" from OAuth consent screens (Google, GitHub, Slack, etc.), create a custom auth config with your own OAuth credentials. See [White-labeling authentication](/docs/white-labeling-authentication) for the full guide.
249 </Accordion>
250
251 <Accordion title="I changed my branding but still see 'Secured by Composio'">
docs/content/docs/configuring-sessions.mdx
+4 -4
@@ -361,7 +361,7 @@ const session = await composio.create("user_123", {
361 </Tab>
362 </Tabs>
363
364 -See [White-labeling authentication](/docs/white-labeling-authentication) for branding, or [Using custom auth configs](/docs/using-custom-auth-configuration) for toolkits that require your own credentials.
364 +See [White-labeling authentication](/docs/white-labeling-authentication) for branding, or [Managed vs custom auth](/docs/custom-app-vs-managed-app) for toolkits that require your own credentials.
365
366 ## Account selection
367
@@ -608,8 +608,8 @@ Returns the first 20 toolkits by default.
608 ## What to read next
609
610 <Cards>
611 - <Card icon={<MessageCircle />} title="In-chat authentication" href="/docs/authenticating-users/in-chat-authentication" description="Let the agent prompt users to connect accounts during conversation" />
612 - <Card icon={<ShieldCheck />} title="Manual authentication" href="/docs/authenticating-users/manually-authenticating" description="Pre-authenticate users before chat using Connect Links and session.authorize()" />
611 + <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Understand the meta tools and toolkit catalog behind session tools" />
612 <Card icon={<Wrench />} title="Enable & disable toolkits" href="/docs/toolkits/enable-and-disable-toolkits" description="Control which toolkits and individual tools are available in sessions" />
614 - <Card icon={<Palette />} title="White-labeling authentication" href="/docs/white-labeling-authentication" description="Use your own OAuth apps so users see your branding on consent screens" />
613 + <Card icon={<Monitor />} title="Workbench" href="/docs/workbench" description="Configure the sandbox for bulk operations and data processing" />
614 + <Card icon={<MessageCircle />} title="In-chat authentication" href="/docs/authenticating-users/in-chat-authentication" description="Let the agent prompt users to connect accounts during conversation" />
615 </Cards>
docs/content/docs/custom-app-vs-managed-app.mdx
+31 -38
@@ -1,13 +1,15 @@
1 ---
2 -title: When to use your own developer credentials
3 -description: When to use your own OAuth credentials instead of Composio managed authentication
2 +title: Managed vs custom auth
3 +description: Decide when to use Composio managed authentication and how to configure your own credentials
4 keywords: [custom auth config, managed auth, oauth, auth config, white label, own developer credentials, decision]
5 ---
6
7 Composio supports two ways to authenticate users with toolkits.
8
9 -- **Composio managed apps**: Composio registers and maintains OAuth apps for popular toolkits (GitHub, Gmail, Slack, etc.). Zero setup, works out of the box.
10 -- **Your own OAuth apps**: You register an OAuth app in the toolkit's developer portal and tell Composio to use your credentials instead.
9 +- **[Composio managed apps](/toolkits/managed-auth)**: Composio registers and maintains OAuth apps for popular toolkits (GitHub, Gmail, Slack, etc.). Zero setup, works out of the box.
10 +- **Custom auth configs**: You provide your own OAuth app, API key, bearer token, or other credentials and tell Composio to use them for a toolkit.
11 +
12 +Use this page as the canonical guide for deciding between managed auth and custom auth configs, then wiring the chosen auth config into a session.
13
14 ## When to use Composio managed apps
15
@@ -17,7 +19,7 @@ Managed apps are the default. Every toolkit that supports OAuth has a Composio m
19 - **Default scopes cover your needs.** Composio requests sensible defaults for each toolkit.
20 - **Branding on consent screens doesn't matter yet.** Users will see "Composio wants to access your account" during OAuth. Fine for internal tools, prototypes, and development. You can still [white-label the Connect Link page](/docs/white-labeling-authentication#customizing-the-connect-link) with your logo and app title without needing your own OAuth app.
21
20 -## When to use your own OAuth app
22 +## When to use a custom auth config
23
24 Bring your own credentials when any of these apply:
25
@@ -28,34 +30,38 @@ Bring your own credentials when any of these apply:
30 - **You're connecting to a custom instance.** Self-hosted or regional variants (e.g., a private Salesforce subdomain) need their own OAuth app.
31 - **Enterprise customers require your branding end-to-end.**
32
33 +## Create a custom auth config
34 +
35 +To check whether a toolkit already has a Composio managed app, see the [managed auth toolkit list](/toolkits/managed-auth). You can still create a custom auth config for branding, scopes, rate limits, polling intervals, or custom instances.
36 +
37 <Steps>
38 <Step>
33 -<StepTitle>Register an OAuth app with the toolkit</StepTitle>
34 -
35 -Go to the toolkit's developer portal and register a new OAuth app. You'll need to set the authorized redirect URI to:
39 +<StepTitle>Create the auth config in the Composio dashboard</StepTitle>
40
37 -```
38 -https://backend.composio.dev/api/v3.1/toolkits/auth/callback
39 -```
41 +In the [Composio dashboard](https://dashboard.composio.dev/~/project/auth-configs):
42
41 -Once registered, copy your **Client ID** and **Client Secret**.
43 +1. Click **Create Auth Config**
44 +2. Select the toolkit
45 +3. Choose the auth scheme (OAuth2, API Key, Bearer Token, etc.)
46 +4. Follow the dashboard instructions for the required credential fields
47
43 -Step-by-step guides for popular toolkits: [Google](https://composio.dev/auth/googleapps) | [GitHub](https://composio.dev/auth/github) | [Slack](https://composio.dev/auth/slack) | [HubSpot](https://composio.dev/auth/hubspot) | [All toolkits](https://composio.dev/auth)
48 +For OAuth toolkits, the dashboard shows the redirect URI to add in the provider's developer portal.
49 </Step>
50
51 <Step>
47 -<StepTitle>Create a custom auth config in Composio</StepTitle>
52 +<StepTitle>Collect credentials from the provider</StepTitle>
53 +
54 +For OAuth toolkits, register an app in the provider's developer portal and add the redirect URI from the dashboard. Then copy the **Client ID** and **Client Secret** back into Composio.
55 +
56 +For API key, bearer token, basic auth, or other auth schemes, collect the credential fields the toolkit requires and enter them in the dashboard.
57
49 -In the [Composio dashboard](https://platform.composio.dev):
58 +Step-by-step OAuth guides: [Google](https://composio.dev/auth/googleapps) | [GitHub](https://composio.dev/auth/github) | [Slack](https://composio.dev/auth/slack) | [HubSpot](https://composio.dev/auth/hubspot) | [All toolkits](https://composio.dev/auth)
59 +</Step>
60
51 -1. Go to **Authentication management** and click **Create Auth Config**
52 -2. Select the toolkit (e.g., GitHub)
53 -3. Choose the **OAuth2** scheme
54 -4. Toggle on **Use your own developer credentials**
55 -5. Enter your **Client ID** and **Client Secret**
56 -6. Click **Create**
61 +<Step>
62 +<StepTitle>Save and copy the auth config ID</StepTitle>
63
58 -Copy the auth config ID (e.g., `ac_1234abcd`).
64 +After you enter the required credentials, click **Create** and copy the auth config ID (for example, `ac_1234abcd`).
65 </Step>
66
67 <Step>
@@ -126,27 +132,14 @@ const session = await composio.create("user_123", {
132 </Tab>
133 </Tabs>
134
129 -### Moving from managed to custom
130 -
131 -Start with managed apps during development. When you're ready for production, register your own OAuth apps for the toolkits that matter and add the `auth_configs` parameter. No other code changes needed.
132 -
133 -If your users already have connections through Composio managed auth, you can import their existing tokens into your new auth config. See [Importing existing connections](/docs/importing-existing-connections).
134 -
135 ### Toolkits without managed auth
136
137 -Some toolkits don't have Composio managed auth. For these, you must create a custom auth config with your own credentials. You can check whether a toolkit has managed auth by calling the API:
138 -
139 -```bash
140 -curl 'https://backend.composio.dev/api/v3.1/toolkits/posthog' \
141 - -H 'x-api-key: YOUR_API_KEY'
142 -```
143 -
144 -If the `composio_managed_auth_schemes` array is empty, you'll need to provide your own credentials. Browse the full list on the [managed auth page](/toolkits/managed-auth) or check individual toolkit pages on the [toolkits page](/toolkits). See [Using custom auth configuration](/docs/using-custom-auth-configuration) for a step-by-step walkthrough.
137 +Some toolkits don't have Composio managed auth. For these, the setup is the same as above, except the provider may ask for API keys or instance details instead of OAuth credentials. Browse the full list on the [managed auth page](/toolkits/managed-auth) or check individual toolkit pages on the [toolkits page](/toolkits).
138
139 ## What to read next
140
141 <Cards>
149 - <Card icon={<Key />} title="Custom auth configs" href="/docs/auth-configuration/custom-auth-configs" description="Detailed setup for custom OAuth apps, API keys, and other auth types" />
142 <Card icon={<Palette />} title="White-labeling authentication" href="/docs/white-labeling-authentication" description="Remove all Composio branding from your auth flows" />
151 - <Card icon={<Wrench />} title="Programmatic auth configs" href="/docs/auth-configuration/programmatic-auth-configs" description="Create and manage auth configs via the SDK" />
143 + <Card icon={<Key />} title="Importing existing connections" href="/docs/importing-existing-connections" description="Bring existing OAuth tokens or API keys into Composio" />
144 + <Card icon={<Database />} title="Managing multiple accounts" href="/docs/managing-multiple-connected-accounts" description="Handle users with multiple accounts for the same toolkit" />
145 </Cards>
docs/content/docs/glossary.mdx
+3 -3
@@ -8,7 +8,7 @@ keywords: [glossary, definitions, terminology]
8 <Glossary>
9
10 <GlossaryTerm name="Auth Config">
11 -A blueprint defining how authentication works for a toolkit: auth method (OAuth2, API key, Bearer token, Basic Auth), scopes, and credentials. Created automatically by a [session](/docs/users-and-sessions) when needed. You can [create a custom one](/docs/auth-configuration/custom-auth-configs) to use your own OAuth credentials or non-default scopes.
11 +A blueprint defining how authentication works for a toolkit: auth method (OAuth2, API key, Bearer token, Basic Auth), scopes, and credentials. Created automatically by a [session](/docs/how-composio-works) when needed. You can [create a custom one](/docs/auth-configuration/custom-auth-configs) to use your own OAuth credentials or non-default scopes.
12 </GlossaryTerm>
13
14 <GlossaryTerm name="Auth Scheme">
@@ -88,7 +88,7 @@ An adapter package that transforms Composio tools into the format expected by an
88 </GlossaryTerm>
89
90 <GlossaryTerm name="Session">
91 -An ephemeral configuration object from `composio.create(userId)`. Ties together a user ID, available toolkits, auth config, and connected accounts. Immutable. Exposes `tools()`, `mcp.url`, `authorize()`, and `toolkits()`. See [Users and sessions](/docs/users-and-sessions).
91 +An ephemeral configuration object from `composio.create(userId)`. Ties together a user ID, available toolkits, auth config, and connected accounts. Immutable. Exposes `tools()`, `mcp.url`, `authorize()`, and `toolkits()`. See [What is a session?](/docs/how-composio-works).
92 </GlossaryTerm>
93
94 <GlossaryTerm name="Session ID">
@@ -132,7 +132,7 @@ The URL Composio delivers signed events to in your application. One per project,
132 </GlossaryTerm>
133
134 <GlossaryTerm name="User ID">
135 -An identifier from your application that Composio uses to scope connected accounts, tool executions, and authorizations. Connections are fully isolated between user IDs. See [Users and sessions](/docs/users-and-sessions).
135 +An identifier from your application that Composio uses to scope connected accounts, tool executions, and authorizations. Connections are fully isolated between user IDs. See [What is a session?](/docs/how-composio-works).
136 </GlossaryTerm>
137
138 <GlossaryTerm name="White-Labeling">
docs/content/docs/how-composio-works.mdx
+102 -67
@@ -1,50 +1,67 @@
1 ---
2 -title: How Composio works
3 -description: Sessions, meta tools, authentication, and tool execution
4 -keywords: [architecture, how it works, sessions, meta tools, execution]
2 +title: What is a session?
3 +description: What Composio sessions do and how they scope users, tools, auth, MCP, and workbench state
4 +keywords: [session, user id, concepts, meta tools, mcp, workbench]
5 ---
6
7 -Composio connects AI agents to external services like GitHub, Gmail, and Slack. Your agent gets a small set of meta tools that can discover, authenticate, and execute tools across hundreds of apps at runtime.
7 +A **session** is the runtime context your agent uses to work for one of your users. It tells Composio whose connected accounts to use, which tools are available, how authentication should happen, and where state should persist while the agent works.
8
9 -This page is a high-level overview. Each concept has a dedicated page with full details:
9 +## The basics
10
11 -1. [Users & Sessions](/docs/users-and-sessions): how users and sessions scope tools and connections
12 -2. [Authentication](/docs/authentication): Connect Links, OAuth, API keys, and auth configs
13 -3. [Tools and toolkits](/docs/tools-and-toolkits): meta tools, discovery, and execution
14 -4. [Workbench](/docs/workbench): persistent Python sandbox for bulk operations
15 -5. [Triggers](/docs/triggers): event-driven payloads from connected apps
11 +When you create a session, Composio gives your agent two ways to access tools:
12
17 -For hands-on setup, see the [quickstart](/docs/quickstart).
13 +- **Native tools** from `session.tools()` for frameworks with tool-calling support.
14 +- **A remote MCP URL** from `session.mcp.url` for MCP-compatible clients.
15
19 -## Sessions
20 -
21 -When your app calls `composio.create()`, it creates a session scoped to a user.
16 +Both point at the same session context.
17
18 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
19 +<Tab value="Python">
20 ```python
24 -composio = Composio()
21 session = composio.create(user_id="user_123")
22
27 -# Get tools formatted for your provider
23 tools = session.tools()
29 -
30 -# Or get the MCP endpoint for MCP-compatible frameworks
24 mcp_url = session.mcp.url
32 -mcp_headers = session.mcp.headers
25 ```
26 +</Tab>
27 +<Tab value="TypeScript">
28 +```typescript
29 +import { Composio } from '@composio/core';
30 +const composio = new Composio({ apiKey: 'your_api_key' });
31 +// ---cut---
32 +const session = await composio.create("user_123");
33 +
34 +const tools = await session.tools();
35 +const mcpUrl = session.mcp.url;
36 +```
37 +</Tab>
38 +</Tabs>
39
40 A session ties together:
41
37 -- **A user**: whose credentials and connections to use
38 -- **Available toolkits**: all by default, or a specific set you configure
39 -- **Auth configuration**: which authentication method and connected accounts to use
42 +- **User ID**: which user's connected accounts and tool executions are in scope.
43 +- **Tool access**: all toolkits by default, or a filtered set of toolkits/tools/tags.
44 +- **Authentication**: managed auth, custom auth configs, and connected account selection.
45 +- **Execution state**: logs, tool memory, MCP state, and workbench files for the task.
46 +
47 +## Users
48 +
49 +A user is an identifier from your app. Connections are stored under that ID, so tools run with the right account and stay isolated from other users.
50
41 -Sessions are immutable. Their configuration is fixed at creation. If the context changes (different toolkits, different connected account), create a new session. You don't need to cache or manage session IDs.
51 +**User ID best practices:**
52
43 -<Card icon={<Database />} title="Users & Sessions" href="/docs/users-and-sessions" description="How users and sessions scope tools and connections" />
53 +- **Recommended:** Database UUID or primary key (`user.id`)
54 +- **Acceptable:** Unique username (`user.username`)
55 +- **Avoid:** Email addresses (they can change)
56 +- **Never:** `default` in production (exposes other users' data)
57
45 -## Meta tools
58 +A user can connect multiple accounts for the same toolkit, such as work and personal Gmail. Use the same user ID, then select the connected account when a session needs a specific account. See [Managing multiple connected accounts](/docs/managing-multiple-connected-accounts).
59
47 -Rather than loading hundreds of tool definitions into your agent's context, a session provides [meta tools](/docs/tools-and-toolkits#meta-tools):
60 +## What sessions do
61 +
62 +### Discover and execute tools
63 +
64 +Instead of loading hundreds of tool definitions into context, a session gives your agent meta tools that discover, authenticate, and execute tools at runtime:
65
66 ```mermaid
67 graph LR
@@ -55,66 +72,84 @@ graph LR
72 C --> F["COMPOSIO_MANAGE_CONNECTIONS"]
73 C --> G["COMPOSIO_MULTI_EXECUTE_TOOL"]
74 C --> H["COMPOSIO_REMOTE_WORKBENCH"]
58 - C --> I["COMPOSIO_REMOTE_BASH_TOOL"]
75 +```
76
60 - D -.- D1["Discover tools by use case"]:::annotation
61 - E -.- E1["Retrieve input schemas for tools"]:::annotation
62 - F -.- F1["Handle OAuth and API keys"]:::annotation
63 - G -.- G1["Run tools with user credentials"]:::annotation
64 - H -.- H1["Persistent Python sandbox"]:::annotation
65 - I -.- I1["File operations and data processing"]:::annotation
77 +The agent searches for relevant tools, authenticates if needed, and executes them through the same session. Meta tool calls share context through the session, so the agent can search in one call and execute in the next without losing state.
78
67 - classDef annotation stroke-dasharray: 5 5
68 -```
79 +### Handle authentication
80
70 -The agent searches for relevant tools, authenticates if needed, and executes them, all through these meta tools. For large responses or bulk operations, the agent offloads work to the workbench sandbox. Meta tool calls share context through a `session_id`, so the agent can search in one call and execute in the next without losing state.
81 +When a tool needs a connection, the session can generate a Connect Link with `session.authorize()` or let the agent handle the flow through `COMPOSIO_MANAGE_CONNECTIONS`.
82
72 -Composio also surfaces **learned plans** from past executions: step-by-step workflows that have worked before for similar tasks, guiding the agent without starting from scratch.
83 +In chat, this means the agent can pause, ask the user to connect an app, then retry the tool once auth is complete. Composio manages the OAuth redirects, token exchange, and refresh. Once a user connects a toolkit, the connected account persists for that user and can be reused by future sessions without re-authentication.
84
74 -<Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Full details on meta tools, discovery, and execution" />
85 +<Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, in-chat auth, manual auth, and custom auth configs" />
86
76 -## Authentication
87 +### Preserve workbench state
88
78 -When a tool requires authentication and the user hasn't connected yet, the agent uses `COMPOSIO_MANAGE_CONNECTIONS` to generate a **Connect Link**, a hosted page where the user authorizes access.
89 +Large responses and bulk operations can be handled in the remote workbench. Instead of stuffing long tool responses into the model context, the agent can use the workbench to read files, search outputs, write Python, transform data, and call Composio tools in bulk.
90
80 -In a conversation, this looks like:
91 +The workbench is scoped to the session, so files, variables, helper functions, and intermediate results stay available while the agent works through a task.
92
82 -> **You:** Create a GitHub issue for the login bug
83 ->
84 -> **Agent:** You'll need to connect your GitHub account. Please authorize here: \<Connect Link\>
85 ->
86 -> **You:** Done
87 ->
88 -> **Agent:** Created issue #42 on your-org/your-repo.
93 +<Card icon={<Monitor />} title="Workbench" href="/docs/workbench" description="Persistent Python sandbox for large responses, bulk operations, and data processing" />
94
90 -Composio manages the OAuth flow end to end: redirects, token exchange, and automatic refresh. Connections persist across sessions. A user who connects GitHub once can use it in every future session without re-authenticating.
95 +## How sessions behave
96
92 -<Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and custom auth configs" />
97 +Every `create()` call returns a new session ID. Use this when you want a fresh task context.
98
94 -## Remote workbench
99 +Sessions persist on the server and do not expire. For multi-turn conversations, store the session ID and reuse it with `composio.use()` rather than calling `create()` again.
100
96 -Large responses from `COMPOSIO_MULTI_EXECUTE_TOOL` are automatically synced to a secure remote workbench. Instead of stuffing thousands of lines into the context window, the agent can work with the data inside the workbench:
101 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
102 +<Tab value="Python">
103 +```python
104 +session = composio.use("session_id")
105 +tools = session.tools()
106 +```
107 +</Tab>
108 +<Tab value="TypeScript">
109 +```typescript
110 +import { Composio } from '@composio/core';
111 +const composio = new Composio({ apiKey: 'your_api_key' });
112 +// ---cut---
113 +const session = await composio.use("session_id");
114 +const tools = await session.tools();
115 +```
116 +</Tab>
117 +</Tabs>
118
98 -- **Reading** files and tool responses
99 -- **Searching** across large outputs
100 -- **Writing and executing** Python code to transform, filter, or aggregate data
101 -- **Calling Composio tools** via the `run_composio_tool` helper for bulk orchestration
119 +You can also update a session without creating a new one:
120
103 -This keeps the agent's context window lean while still letting it handle operations like labeling hundreds of emails, processing CSV exports, or summarizing long API responses.
121 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
122 +<Tab value="Python">
123 +```python
124 +session.update(
125 + toolkits=["gmail", "slack"],
126 + auth_configs={"gmail": "ac_new_config"},
127 + connected_accounts={"slack": ["ca_work_slack"]},
128 +)
129 +```
130 +</Tab>
131 +<Tab value="TypeScript">
132 +```typescript
133 +import { Composio } from '@composio/core';
134 +const composio = new Composio({ apiKey: 'your_api_key' });
135 +const session = await composio.use("session_id");
136 +// ---cut---
137 +await session.update({
138 + toolkits: ["gmail", "slack"],
139 + authConfigs: { gmail: "ac_new_config" },
140 + connectedAccounts: { slack: ["ca_work_slack"] },
141 +});
142 +```
143 +</Tab>
144 +</Tabs>
145
105 -<Card icon={<Monitor />} title="Workbench" href="/docs/workbench" description="Persistent Python sandbox for large-context operations" />
146 +Create a new session for a different user or fundamentally different task setup. Reuse or update the session when the same conversation should keep its tool, auth, and workbench context.
147
148 ## What to read next
149
109 -Start with the concepts in order, or jump to the quickstart to build right away:
110 -
150 <Cards>
112 - <Card icon={<Database />} title="Users & Sessions" href="/docs/users-and-sessions" description="How users and sessions scope tools and connections" />
151 + <Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions" description="Enable toolkits, set auth configs, and select connected accounts" />
152 + <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="How meta tools discover, authenticate, and execute tools" />
153 <Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and auth configs" />
114 - <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Meta tools, discovery, and execution" />
115 - <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build your first agent" />
154 + <Card icon={<Monitor />} title="Workbench" href="/docs/workbench" description="Write and run code in a persistent sandbox" />
155 </Cards>
117 -
118 -Deciding how to connect? See:
119 -- [Native Tools vs MCP](/docs/native-tools-vs-mcp) — SDK vs MCP servers
120 -- [Sessions vs Direct Execution](/docs/sessions-vs-direct-execution) — meta tools vs fetching specific tools
docs/content/docs/importing-existing-connections.mdx
+2 -2
@@ -332,7 +332,7 @@ const session = await composio.create('user_123', {
332 ## What to read next
333
334 <Cards>
335 - <Card icon={<Key />} title="Custom auth configs" href="/docs/using-custom-auth-configuration" description="Set up auth configs with your own OAuth credentials" />
336 - <Card icon={<Database />} title="Connected accounts" href="/docs/auth-configuration/connected-accounts" description="Manage connected accounts after importing" />
335 + <Card icon={<Database />} title="Managing multiple accounts" href="/docs/managing-multiple-connected-accounts" description="Pin and select connected accounts for a user" />
336 <Card icon={<Palette />} title="White-labeling" href="/docs/white-labeling-authentication" description="Use your own branding on OAuth consent screens" />
337 + <Card icon={<Key />} title="Connection expiry events" href="/docs/subscribing-to-connection-expiry-events" description="Detect expired OAuth connections and prompt re-authentication" />
338 </Cards>
docs/content/docs/meta.json
+16 -19
@@ -5,37 +5,34 @@
5 "quickstart",
6 "providers",
7 "cli",
8 - "---Core Concepts---",
8 + "---Customizing sessions---",
9 "how-composio-works",
10 - "users-and-sessions",
11 - "authentication",
10 + "configuring-sessions",
11 "tools-and-toolkits",
12 + "toolkits",
13 "workbench",
14 - "triggers",
15 - "---Getting Started---",
16 - "configuring-sessions",
14 + "---Authenticate users---",
15 + "authentication",
16 "authenticating-users",
18 - "toolkits",
19 - "setting-up-triggers",
20 - "---Guides---",
17 + "custom-app-vs-managed-app",
18 "white-labeling-authentication",
22 - "managing-multiple-connected-accounts",
23 - "using-custom-auth-configuration",
19 "importing-existing-connections",
25 - "webhook-verification",
20 + "managing-multiple-connected-accounts",
21 "subscribing-to-connection-expiry-events",
27 - "custom-app-vs-managed-app",
28 - "native-tools-vs-mcp",
22 + "---Triggers and webhooks---",
23 + "triggers",
24 + "setting-up-triggers",
25 + "webhook-verification",
26 + "---Direct Tool Execution Guides (Legacy)---",
27 "sessions-vs-direct-execution",
28 + "tools-direct",
29 + "auth-configuration",
30 + "---Other topics---",
31 + "native-tools-vs-mcp",
32 "proxy-execute",
31 - "---Features---",
33 "projects",
34 "observability",
35 "single-toolkit-mcp",
35 - "---Direct Tool Execution Guides---",
36 - "tools-direct",
37 - "auth-configuration",
38 - "---Resources---",
36 "signing-up-as-an-agent",
37 "common-faq",
38 "glossary",
docs/content/docs/migration-guide/direct-to-sessions.mdx
+2 -2
@@ -8,7 +8,7 @@ This guide is for developers who are using Composio's **direct tool execution**
8
9 With sessions, you don't need to manage tool fetching, authentication, or execution yourself. You create a session and it handles everything. Your existing auth configs and connected accounts carry over, so your users don't need to re-authenticate.
10
11 -If you're starting fresh, skip this guide and head to the [Quickstart](/docs/quickstart).
11 +If you're starting fresh, use [Configuring Sessions](/docs/configuring-sessions) instead.
12
13 ## What changes
14
@@ -280,6 +280,6 @@ See [White-labeling authentication](/docs/white-labeling-authentication) for mor
280 ## Get started
281
282 <Cards>
283 - <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build your first agent with sessions" />
283 <Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions" description="Toolkits, auth configs, account selection, and session methods" />
284 + <Card icon={<Database />} title="What is a session?" href="/docs/how-composio-works" description="Understand how sessions scope tools and connected accounts" />
285 </Cards>
docs/content/docs/migration-guide/new-sdk.mdx
+1 -1
@@ -4,7 +4,7 @@ description: Learn more about Composio's next generation SDKs and how to migrate
4 ---
5
6 <Callout type="info">
7 -This guide covers migrating from the legacy SDK (v1) to the current SDK (v3). The recommended way to use Composio is now through **sessions** — see [Migrating from Direct Tools to Sessions](/docs/migration-guide/direct-to-sessions) or the [Quickstart](/docs/quickstart) if you're starting fresh.
7 +This guide covers migrating from the legacy SDK (v1) to the current SDK (v3). The recommended way to use Composio is now through **sessions** — see [Migrating from Direct Tools to Sessions](/docs/migration-guide/direct-to-sessions) or [Configuring Sessions](/docs/configuring-sessions) if you're starting fresh.
8 </Callout>
9
10 In the last few months, we have experienced very rapid growth in usage of our platform. As such, our team has been working hard to radically improve the performance and developer experience of our platform.
docs/content/docs/migration-guide/tool-router-beta.mdx
+2 -2
@@ -6,7 +6,7 @@ keywords: [upgrade, migrate, experimental, beta, tool router]
6
7 This guide is for users who adopted the **experimental tool router** (`composio.experimental.tool_router`) during its beta period. The tool router has now graduated to a stable, first-class feature called **sessions** — with a simpler API, better auth handling, and full framework support.
8
9 -If you never used `composio.experimental.tool_router`, you can skip this guide and head straight to the [Quickstart](/docs/quickstart).
9 +If you never used `composio.experimental.tool_router`, you can skip this guide and start with [Configuring Sessions](/docs/configuring-sessions).
10
11 ## The basics
12
@@ -104,6 +104,6 @@ const session = await composio.create('user_123',
104 ## Get started
105
106 <Cards>
107 - <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build your first agent with the stable sessions API" />
107 <Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions" description="Restrict toolkits, set auth configs, and select connected accounts" />
108 + <Card icon={<Database />} title="What is a session?" href="/docs/how-composio-works" description="Understand the stable sessions model" />
109 </Cards>
docs/content/docs/migration-guide/toolkit-versioning.mdx
+3 -3
@@ -159,7 +159,7 @@ The `dangerouslySkipVersionCheck` flag is only for migration or debugging. Never
159 ## What to read next
160
161 <Cards>
162 - <Card icon={<Blocks />} title="Toolkit versioning" href="/docs/tools-direct/toolkit-versioning" description="Complete guide to version formats, resolution order, and managing versions" />
163 - <Card icon={<Rocket />} title="Migrate to sessions" href="/docs/migration-guide/direct-to-sessions" description="Move from direct tool execution to the sessions pattern" />
164 - <Card icon={<Play />} title="Quickstart" href="/docs/quickstart" description="Build your first agent with the sessions API" />
162 + <Card icon={<Rocket />} title="Migrate to sessions" href="/docs/migration-guide/direct-to-sessions" description="Move from older tool execution patterns to sessions" />
163 + <Card icon={<Wrench />} title="Configuring sessions" href="/docs/configuring-sessions" description="Control toolkits, auth configs, connected accounts, and tool availability" />
164 + <Card icon={<Blocks />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Understand tool discovery and toolkit access in sessions" />
165 </Cards>
docs/content/docs/native-tools-vs-mcp.mdx
+1 -3
@@ -133,11 +133,9 @@ const tools = await client.tools();
133 </Tab>
134 </Tabs>
135
136 -See the [quickstart](/docs/quickstart) for full working examples.
137 -
136 ## Next steps
137
138 <Cards>
141 - <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build an agent with sessions" />
139 <Card icon={<Key />} title="Providers" href="/docs/providers" description="OpenAI, Anthropic, Vercel AI, LangChain" />
140 + <Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions" description="Configure native tools or MCP endpoints for a session" />
141 </Cards>
docs/content/docs/projects.mdx
+1 -1
@@ -96,6 +96,6 @@ You can also view and update these from **Settings > Project Settings** in the [
96
97 <Cards>
98 <Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Auth configs are scoped to projects — learn how Composio manages auth" />
99 - <Card icon={<Database />} title="Users & Sessions" href="/docs/users-and-sessions" description="Connected accounts and sessions live within a project" />
99 + <Card icon={<Database />} title="What is a session?" href="/docs/how-composio-works" description="Connected accounts and sessions live within a project" />
100 <Card icon={<Zap />} title="Triggers" href="/docs/triggers" description="Webhook configurations are project-scoped" />
101 </Cards>
docs/content/docs/proxy-execute.mdx
+2 -3
@@ -340,8 +340,7 @@ Proxy execute forwards the upstream response verbatim — `status`, `headers`, a
340 ## What to read next
341
342 <Cards>
343 - <Card icon={<Wrench />} title="Executing tools" href="/docs/tools-direct/executing-tools" description="Run predefined Composio tools with sessions or direct calls" />
344 - <Card icon={<Code />} title="Custom tools" href="/docs/tools-direct/custom-tools" description="Wrap a proxy call in a reusable custom tool with its own schema" />
345 - <Card icon={<Key />} title="Connected accounts" href="/docs/auth-configuration/connected-accounts" description="Create, list, and manage the connected accounts used by proxy execute" />
343 <Card icon={<Terminal />} title="API reference" href="/reference/api-reference/tools/postToolsExecuteProxy" description="Full request and response schema for POST /api/v3.1/tools/execute/proxy" />
344 + <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="Understand how Composio tools are discovered and executed in sessions" />
345 + <Card icon={<Key />} title="Authentication" href="/docs/authentication" description="How Composio manages OAuth, API keys, and connected accounts" />
346 </Cards>
docs/content/docs/quickstart.mdx
+3 -3
@@ -4,7 +4,7 @@ description: Build an AI agent with access to 1000+ tools
4 keywords: [tutorial, setup, first agent]
5 ---
6
7 -Build your first AI agent with Composio Tools. You'll create a [session](/docs/users-and-sessions) for a user, give your agent access to [tools](/docs/tools-and-toolkits), and let it take action across 1000+ apps.
7 +Build your first AI agent with Composio Tools. You'll create a [session](/docs/how-composio-works) for a user, give your agent access to [tools](/docs/tools-and-toolkits), and let it take action across 1000+ apps.
8
9 <QuickstartFlow>
10
@@ -867,14 +867,14 @@ readline.close();
867
868 </QuickstartFlow>
869
870 -By default, each `composio.create()` call returns a new session with access to all toolkits. Sessions are highly configurable beyond that: [Reusing a session](/docs/users-and-sessions#reusing-a-session) covers storing a session ID and calling `composio.use()` across multi-turn requests, while [Configuring Sessions](/docs/configuring-sessions) covers restricting toolkits, auth configs, and connected accounts.
870 +By default, each `composio.create()` call returns a new session with access to all toolkits. Sessions are highly configurable beyond that: [Reusing a session](/docs/how-composio-works#how-sessions-behave) covers storing a session ID and calling `composio.use()` across multi-turn requests, while [Configuring Sessions](/docs/configuring-sessions) covers restricting toolkits, auth configs, and connected accounts.
871
872 ## Next steps
873
874 <Cards>
875 <Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions" description="Restrict toolkits, set custom auth configs, and select connected accounts" />
876 <Card icon={<Key />} title="Authenticating Users" href="/docs/authentication" description="Learn how users connect their accounts via Connect Links, OAuth, and API keys" />
877 - <Card icon={<BookOpen />} title="How Composio works" href="/docs/how-composio-works" description="Understand what happens under the hood: sessions, meta tools, and the tool execution lifecycle" />
877 + <Card icon={<BookOpen />} title="What is a session?" href="/docs/how-composio-works" description="Understand what happens under the hood: sessions, meta tools, and the tool execution lifecycle" />
878 <Card icon={<Play />} title="Build a chat app" href="/cookbooks/chat-app" description="Full Next.js tutorial: tool discovery, auth, and multi-turn conversations" />
879 </Cards>
880
docs/content/docs/sessions-vs-direct-execution.mdx
+1 -2
@@ -185,7 +185,6 @@ See the [migration guide](/docs/migration-guide/direct-to-sessions). Auth config
185 ## Next steps
186
187 <Cards>
188 - <Card icon={<Rocket />} title="Quickstart" href="/docs/quickstart" description="Build an agent with sessions" />
188 <Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions" description="Toolkits, auth configs, and connected accounts" />
190 - <Card icon={<Wrench />} title="Direct Tool Execution" href="/docs/tools-direct/executing-tools" description="Fetch and execute specific tools" />
189 + <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="How sessions discover and execute tools at runtime" />
190 </Cards>
docs/content/docs/setting-up-triggers/managing-triggers.mdx
+1 -1
@@ -125,7 +125,7 @@ Deleting a trigger is permanent. Use `disable()` instead to temporarily stop rec
125 ## What to read next
126
127 <Cards>
128 + <Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/webhook-verification" description="Validate webhook signatures to ensure payloads are authentic" />
129 <Card icon={<Zap />} title="Creating triggers" href="/docs/setting-up-triggers/creating-triggers" description="Create trigger instances to start receiving events from connected apps" />
130 <Card icon={<Zap />} title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Set up webhooks or SDK subscriptions to handle trigger events" />
130 - <Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/webhook-verification" description="Validate webhook signatures to ensure payloads are authentic" />
131 </Cards>
docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
+1 -1
@@ -230,7 +230,7 @@ Use `trigger_id` to match events to a specific trigger instance, or `trigger_slu
230 ## What to read next
231
232 <Cards>
233 - <Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/webhook-verification" description="Validate webhook signatures to ensure payloads are authentic" />
233 <Card icon={<Zap />} title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="List, enable, disable, and delete trigger instances" />
234 + <Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/webhook-verification" description="Validate webhook signatures to ensure payloads are authentic" />
235 <Card icon={<Zap />} title="Troubleshooting triggers" href="/docs/troubleshooting/triggers" description="Not receiving events? Check common trigger issues and how to fix them" />
236 </Cards>
docs/content/docs/single-toolkit-mcp.mdx
+3 -3
@@ -6,7 +6,7 @@ deprecated: true
6 ---
7
8 <Callout type="info">
9 -For most use cases, we recommend using the [quickstart](/docs/quickstart). This provides dynamic tool access and a much better MCP experience with context management handled by us.
9 +For most use cases, use a regular [session](/docs/configuring-sessions) instead. Sessions provide dynamic tool access and a much better MCP experience with context management handled by us.
10 </Callout>
11
12 ## Install the SDK
@@ -328,7 +328,7 @@ if (result.deleted) {
328 <Card title="Providers" href="/docs/providers">
329 Use with Anthropic, OpenAI, and other frameworks
330 </Card>
331 - <Card title="Quickstart" href="/docs/quickstart">
332 - Build an agent (recommended)
331 + <Card title="Configuring Sessions" href="/docs/configuring-sessions">
332 + Configure the recommended dynamic MCP endpoint
333 </Card>
334 </Cards>
docs/content/docs/toolkits/custom-tools-and-toolkits.mdx
+3 -3
@@ -398,7 +398,7 @@ import { z } from "zod/v3";
398 // ---cut---
399
400 const userManagement = experimental_createToolkit("USER_MANAGEMENT", {
401 - name: "User management",
401 + name: "User scoping",
402 description: "Manage user roles and permissions",
403 tools: [
404 experimental_createTool("ASSIGN_ROLE", {
@@ -424,7 +424,7 @@ composio = Composio(api_key="your_api_key")
424
425 user_management = composio.experimental.Toolkit(
426 slug="USER_MANAGEMENT",
427 - name="User management",
427 + name="User scoping",
428 description="Manage user roles and permissions",
429 )
430
@@ -638,7 +638,7 @@ custom_toolkits = session.custom_toolkits()
638
639 ## Reusing a session with custom tools
640
641 -When [reusing a session](/docs/users-and-sessions#reusing-a-session) via `composio.use()`, you can attach custom tools at the same time:
641 +When [reusing a session](/docs/how-composio-works#how-sessions-behave) via `composio.use()`, you can attach custom tools at the same time:
642
643 <Tabs groupId="language" items={['TypeScript', 'Python']} persist>
644 <Tab value="TypeScript">
docs/content/docs/toolkits/enable-and-disable-toolkits.mdx
+1 -1
@@ -270,8 +270,8 @@ const session = await composio.create("user_123", {
270 ## What to read next
271
272 <Cards>
273 + <Card icon={<Wrench />} title="Custom tools and toolkits" href="/docs/toolkits/custom-tools-and-toolkits" description="Define local tools that run alongside remote Composio tools" />
274 <Card icon={<Wrench />} title="Fetching tools and toolkits" href="/docs/toolkits/fetching-tools-and-toolkits" description="List enabled toolkits, get meta tools, and browse the catalog" />
275 <Card icon={<Wrench />} title="Configuring sessions" href="/docs/configuring-sessions" description="Auth configs, connected accounts, and other session options" />
275 - <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="How meta tools discover, authenticate, and execute tools at runtime" />
276 </Cards>
277
docs/content/docs/tools-and-toolkits.mdx
+19 -22
@@ -4,11 +4,17 @@ description: Understand how tools and toolkits work in Composio
4 keywords: [tools, toolkits, meta tools, context management]
5 ---
6
7 -Composio offers 1000+ toolkits, but loading all the tools into context would overwhelm your agent. Instead, your agent has access to meta tools that discover, authenticate, and execute the right tools at runtime.
7 +A **toolkit** is a collection of related tools for a service. For example, the `github` toolkit contains tools for creating issues, managing pull requests, and starring repositories.
8 +
9 +A **tool** is an individual action your agent can execute. Each tool has an input schema (required and optional parameters) and an output schema (what it returns). Tools follow a `{TOOLKIT}_{ACTION}` naming pattern, like `GITHUB_CREATE_ISSUE`.
10
11 ## Meta tools
12
11 -When you create a session, your agent gets these meta tools:
13 +When using a Composio session, your agent primarily interfaces with tools and toolkits through meta tools. These tools let the agent search the catalog, inspect schemas, authenticate users, execute app tools, and use the workbench without loading every possible tool into context.
14 +
15 +If you know exactly which tools the agent should use, you can [preload those tools or use the direct tools preset](/docs/configuring-sessions#direct-tools-preset) to expose them directly and disable meta tools.
16 +
17 +A session provides these meta tools:
18
19 | Meta tool | What it does |
20 |-----------|--------------|
@@ -61,43 +67,34 @@ For most tasks, `COMPOSIO_MULTI_EXECUTE_TOOL` returns results directly. But when
67
68 - **`COMPOSIO_REMOTE_BASH_TOOL`** - Execute bash commands for simpler file operations and data extraction using tools like `jq`, `awk`, `sed`, and `grep`.
69
64 -## Toolkits and tools
65 -
66 -A **toolkit** is a collection of related tools for a service. For example, the `github` toolkit contains tools for creating issues, managing pull requests, and starring repositories.
67 -
68 -A **tool** is an individual action your agent can execute. Each tool has an input schema (required and optional parameters) and an output schema (what it returns). Tools follow a `{TOOLKIT}_{ACTION}` naming pattern, like `GITHUB_CREATE_ISSUE`.
69 -
70 -<Callout>
71 -If you know exactly which tools you need, you can [execute them directly](/docs/tools-direct/executing-tools) without meta tools.
72 -</Callout>
70 +## Custom tools and toolkits
71
72 You can also add local in-process tools to a session using the experimental custom tools and custom toolkits API. See [Custom tools and toolkits](/docs/toolkits/custom-tools-and-toolkits).
73
76 -## Default toolkit access
74 +## What toolkits does my agent have access to?
75
78 -<Accordions>
79 -<Accordion title="What toolkits can my agent access by default?">
80 -All of them. When you create a session without specifying a `toolkits` parameter, every toolkit in the Composio catalog is discoverable through `COMPOSIO_SEARCH_TOOLS`. The agent searches for relevant tools at runtime — it doesn't load them all into context at once.
76 +All toolkits are discoverable by default. When you create a session without specifying a `toolkits` parameter, every toolkit in the Composio catalog is available through `COMPOSIO_SEARCH_TOOLS`. The agent searches for relevant tools at runtime — it doesn't load them all into context at once.
77
78 To restrict which toolkits are available, pass `toolkits` when creating the session. See [Enable and disable toolkits](/docs/toolkits/enable-and-disable-toolkits).
83 -</Accordion>
84 -</Accordions>
79
80 ## Authentication
81
82 Tools execute with the user's authenticated credentials. When a user connects their GitHub account, all GitHub tools run with their permissions.
83
84 +For OAuth toolkits, Composio uses [managed apps](/docs/custom-app-vs-managed-app) by default. Use a custom app when you need your own OAuth branding, scopes, or consent screen.
85 +
86 If a tool requires authentication and the user hasn't connected yet, the agent can use `COMPOSIO_MANAGE_CONNECTIONS` to prompt them.
87
92 -<Card icon={<Key />} title="Authentication" href="/docs/authentication">
93 - Learn how Composio handles user authentication
94 -</Card>
88 +<Cards>
89 + <Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Learn how Composio handles user authentication" />
90 + <Card icon={<Key />} title="Managed vs custom apps" href="/docs/custom-app-vs-managed-app" description="Choose between Composio managed OAuth apps and your own OAuth app" />
91 +</Cards>
92
93 ## What to read next
94
95 <Cards>
96 + <Card icon={<Wrench />} title="Fetching tools" href="/docs/toolkits/fetching-tools-and-toolkits" description="Browse the catalog and fetch tools for sessions" />
97 + <Card icon={<Wrench />} title="Enable & disable toolkits" href="/docs/toolkits/enable-and-disable-toolkits" description="Control which toolkits and individual tools are available in sessions" />
98 <Card icon={<Monitor />} title="Workbench" href="/docs/workbench" description="Persistent Python sandbox for bulk operations and data processing" />
99 <Card icon={<Blocks />} title="Browse toolkits" href="/toolkits" description="Explore all available toolkits" />
101 - <Card icon={<Wrench />} title="Fetching tools" href="/docs/toolkits/fetching-tools-and-toolkits" description="Browse the catalog and fetch tools for sessions" />
102 - <Card icon={<Zap />} title="Direct tool execution" href="/docs/tools-direct/executing-tools" description="Execute tools without meta tools for deterministic workflows" />
100 </Cards>
docs/content/docs/tools-direct/authenticating-tools.mdx
+1 -1
@@ -94,7 +94,7 @@ With an auth config created, you're ready to authenticate your users!
94 You can either use [**Connect Link**](#hosted-authentication-connect-link) for a hosted authentication flow, or use [**Direct SDK Setup**](#direct-sdk-setup).
95
96 <Callout>
97 -User authentication requires a User ID - a unique identifier that groups connected accounts together. Learn more about [User Management](/docs/users-and-sessions) to understand how to structure User IDs for your application.
97 +User authentication requires a User ID - a unique identifier that groups connected accounts together. Learn more about [User scoping](/docs/how-composio-works) to understand how to structure User IDs for your application.
98 </Callout>
99
100 **Choose the section below that matches your toolkit's authentication method:**
docs/content/docs/tools-direct/executing-tools.mdx
+2 -2
@@ -6,7 +6,7 @@ llmGuardrails: "direct-execution"
6 ---
7
8 <Callout type="info">
9 -If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. Sessions handle tool fetching, authentication, and execution automatically. See the [quickstart](/docs/quickstart) to get started, or [Sessions vs Direct Execution](/docs/sessions-vs-direct-execution) to understand the tradeoffs.
9 +If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. Sessions handle tool fetching, authentication, and execution automatically. See [Sessions vs Direct Execution](/docs/sessions-vs-direct-execution) to understand the tradeoffs.
10 </Callout>
11
12 LLMs on their own can only do generation. Tool calling changes that by letting them interact with external services. Instead of just drafting an email, the model can call `GMAIL_SEND_EMAIL` to actually send it. The tool's results feed back to the LLM, closing the loop so it can decide, act, observe, and adapt.
@@ -14,7 +14,7 @@ LLMs on their own can only do generation. Tool calling changes that by letting t
14 In Composio, every **tool** is a single API action—fully described with schema, parameters, and return type. Tools live inside **toolkits** like Gmail, Slack, or GitHub, and Composio handles authentication and user scoping.
15
16 <Callout type="info">
17 -**User Scoping**: All tools are scoped to a specific user - that's why every example includes a `user_id`. Learn how to structure User IDs in [User Management](/docs/users-and-sessions). Each user must authenticate with their respective services (Gmail, Calendar, etc.) - see [Authentication](/docs/tools-direct/authenticating-tools).
17 +**User Scoping**: All tools are scoped to a specific user - that's why every example includes a `user_id`. Learn how to structure User IDs in [User scoping](/docs/how-composio-works). Each user must authenticate with their respective services (Gmail, Calendar, etc.) - see [Authentication](/docs/tools-direct/authenticating-tools).
18 </Callout>
19
20 ## Using Chat Completions
docs/content/docs/tools-direct/fetching-tools.mdx
+1 -1
@@ -35,7 +35,7 @@ const tools = await composio.tools.get(userId, {
35 </Tab>
36 </Tabs>
37
38 -Returns top 20 tools by default. Tools require a `user_id` because they're scoped to authenticated accounts. See [User management](/docs/users-and-sessions) and [Authentication](/docs/tools-direct/authenticating-tools).
38 +Returns top 20 tools by default. Tools require a `user_id` because they're scoped to authenticated accounts. See [User scoping](/docs/how-composio-works) and [Authentication](/docs/tools-direct/authenticating-tools).
39
40 ## Tool schemas
41
docs/content/docs/triggers.mdx
+1 -1
@@ -30,7 +30,7 @@ Composio handles ingress setup on most webhook triggers. For some webhook trigge
30 A trigger type is a template that defines what event to listen for and what configuration is required. For example, `GITHUB_COMMIT_EVENT` requires an `owner` and `repo`. Each toolkit exposes its own set of trigger types.
31 </Accordion>
32 <Accordion title="What is a trigger instance?">
33 -When you create a trigger from a type, it's scoped to a specific [user and connected account](/docs/users-and-sessions). For example, creating a `GITHUB_COMMIT_EVENT` trigger for user `alice` on the `composio` repo produces a trigger instance with its own `ti_*` ID that you can enable, disable, or delete independently.
33 +When you create a trigger from a type, it's scoped to a specific [user and connected account](/docs/how-composio-works). For example, creating a `GITHUB_COMMIT_EVENT` trigger for user `alice` on the `composio` repo produces a trigger instance with its own `ti_*` ID that you can enable, disable, or delete independently.
34 </Accordion>
35 </Accordions>
36
docs/content/docs/users-and-sessions.mdx deleted
-183
@@ -1,183 +0,0 @@
1 ----
2 -title: Users & Sessions
3 -description: How Composio scopes tools and connections to your users
4 -keywords: [session, user id, concepts]
5 ----
6 -
7 -When building AI agents for multiple users, each user needs their own connections and context. This is represented through **users** and **sessions**.
8 -
9 -<Callout>
10 -For a hands-on walkthrough, see the [quickstart](/docs/quickstart).
11 -</Callout>
12 -
13 -## Users
14 -
15 -A user is an identifier from your app. When someone connects their Gmail or GitHub, that connection is stored under their user ID, so tools always run with the right authentication. Every tool execution and authorization uses the user ID to identify the context. Connections are fully isolated between user IDs.
16 -
17 -<Accordions>
18 -<Accordion title="Best practices for User IDs">
19 -- **Recommended:** Database UUID or primary key (`user.id`)
20 -- **Acceptable:** Unique username (`user.username`)
21 -- **Avoid:** Email addresses (they can change)
22 -- **Never:** `default` in production (exposes other users' data)
23 -</Accordion>
24 -</Accordions>
25 -
26 -A user can have multiple connections to the same toolkit.
27 -Let's say you want to allow users to connect both their work and personal email. You can represent the user with the same user ID but differentiate between the two with the connected
28 -account ID.
29 -
30 -Here is a detailed guide on how to manage such connections:
31 -<Card icon={<Plug />} title="Managing Multiple Connections" href="/docs/managing-multiple-connected-accounts" description="Handle multiple accounts per toolkit for a single user" />
32 -
33 -Triggers are scoped to a connected account. When you create a trigger, it's tied to a specific user's connection:
34 -<Card icon={<Zap />} title="Triggers" href="/docs/triggers" description="Event-driven payloads from connected apps" />
35 -
36 -
37 -## Sessions
38 -
39 -A session is an ephemeral configuration. You specify:
40 -
41 -- Which user's authorization and data the agent will access
42 -- What toolkits are enabled or disabled
43 -- What authentication method, scopes, and credentials to use
44 -
45 -### Creating a session
46 -
47 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
48 -<Tab value="Python">
49 -```python
50 -session = composio.create(user_id="user_123")
51 -```
52 -</Tab>
53 -<Tab value="TypeScript">
54 -```typescript
55 -import { Composio } from '@composio/core';
56 -const composio = new Composio({ apiKey: 'your_api_key' });
57 -// ---cut---
58 -const session = await composio.create("user_123");
59 -```
60 -</Tab>
61 -</Tabs>
62 -
63 -### Session methods
64 -
65 -Once created, a session provides methods to get tools and manage connections:
66 -
67 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
68 -<Tab value="Python">
69 -```python
70 -# Get tools for your AI framework
71 -tools = session.tools()
72 -
73 -# Get MCP server URL
74 -mcp_url = session.mcp.url
75 -
76 -# Authenticate a user to a toolkit
77 -connection_request = session.authorize("github")
78 -
79 -# List available toolkits and their connection status
80 -toolkits = session.toolkits()
81 -```
82 -</Tab>
83 -<Tab value="TypeScript">
84 -```typescript
85 -import { Composio } from '@composio/core';
86 -const composio = new Composio({ apiKey: 'your_api_key' });
87 -const session = await composio.create("user_123");
88 -// ---cut---
89 -// Get tools for your AI framework
90 -const tools = await session.tools();
91 -
92 -// Get MCP server URL
93 -const mcpUrl = session.mcp.url;
94 -
95 -// Authenticate a user to a toolkit
96 -const connectionRequest = await session.authorize("github");
97 -
98 -// List available toolkits and their connection status
99 -const toolkits = await session.toolkits();
100 -```
101 -</Tab>
102 -</Tabs>
103 -
104 -## How sessions behave
105 -
106 -A session ties together a user, a set of available toolkits, auth configuration for those toolkits, and connected accounts. Each session is designed for a particular agentic task.
107 -
108 -Every call to `create()` returns a new session ID, even if the configuration is identical. This gives you clean isolation between tasks and makes it easy to trace activity back to a specific session in logs and analytics.
109 -
110 -Sessions persist on the server and don't expire. For multi-turn conversations, store the session ID and reuse it with `composio.use()` rather than calling `create()` again.
111 -
112 -### Reusing a session
113 -
114 -In multi-turn chat apps, you create a session once and reuse it across requests. Store the session ID and call `composio.use()` to rehydrate it:
115 -
116 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
117 -<Tab value="Python">
118 -```python
119 -session = composio.use("session_id")
120 -tools = session.tools()
121 -```
122 -</Tab>
123 -<Tab value="TypeScript">
124 -```typescript
125 -import { Composio } from '@composio/core';
126 -const composio = new Composio({ apiKey: 'your_api_key' });
127 -// ---cut---
128 -const session = await composio.use("session_id");
129 -const tools = await session.tools();
130 -```
131 -</Tab>
132 -</Tabs>
133 -
134 -This returns the same session with the same toolkits, auth configs, and connected accounts.
135 -
136 -### Updating a session
137 -
138 -Use `session.update()` to modify a session's configuration without creating a new one. Only the fields you pass are changed — everything else is preserved.
139 -
140 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
141 -<Tab value="Python">
142 -```python
143 -session.update(
144 - toolkits=["gmail", "slack"],
145 - auth_configs={"gmail": "ac_new_config"},
146 - connected_accounts={"slack": ["ca_work_slack"]},
147 -)
148 -```
149 -</Tab>
150 -<Tab value="TypeScript">
151 -```typescript
152 -import { Composio } from '@composio/core';
153 -const composio = new Composio({ apiKey: 'your_api_key' });
154 -const session = await composio.create("user_123");
155 -// ---cut---
156 -await session.update({
157 - toolkits: ["gmail", "slack"],
158 - authConfigs: { gmail: "ac_new_config" },
159 - connectedAccounts: { slack: ["ca_work_slack"] },
160 -});
161 -```
162 -</Tab>
163 -</Tabs>
164 -
165 -You can update toolkits, auth configs, connected accounts, workbench settings, multi-account config, manage connections, tags, tools, and preload. See [Configuring Sessions](/docs/configuring-sessions) for the full list of options.
166 -
167 -### Connected accounts persist across sessions
168 -
169 -Connections are tied to the user ID, not the session. A user who connected Gmail in one session can access it in every future session without re-authenticating.
170 -
171 -<Accordions>
172 -<Accordion title="When should I create a new session?">
173 -Reuse a session with `composio.use()` for multi-turn conversations. Create a new session when you need a fundamentally different setup (e.g., a different user or a completely different set of toolkits).
174 -</Accordion>
175 -</Accordions>
176 -
177 -## What to read next
178 -
179 -<Cards>
180 - <Card icon={<Key />} title="Authentication" href="/docs/authentication" description="Connect Links, OAuth, API keys, and auth configs" />
181 - <Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions" description="Enable toolkits, set auth configs, and select connected accounts" />
182 - <Card icon={<Monitor />} title="Workbench" href="/docs/workbench" description="Write and run code in a persistent sandbox" />
183 -</Cards>
docs/content/docs/using-custom-auth-configuration.mdx deleted
-81
@@ -1,81 +0,0 @@
1 ----
2 -title: Using custom auth configuration
3 -description: Set up auth configs for toolkits without Composio managed authentication
4 -keywords: [custom credentials, no managed auth]
5 ----
6 -
7 -You create a custom auth config when you need to provide your own credentials for a toolkit. Common reasons:
8 -
9 -- **Toolkit has no managed auth**: PostHog, Tavily, Perplexity, etc. require your own credentials
10 -- **White-labeling**: Show your app name on OAuth consent screens instead of "Composio". See [White-labeling authentication](/docs/white-labeling-authentication)
11 -- **Rate limits**: Composio's default OAuth app shares quota across all users. Your own app gets a dedicated quota
12 -- **Faster polling triggers**: Composio managed auth enforces a 15-minute minimum polling interval. Your own OAuth app can use shorter polling intervals where supported
13 -- **Custom scopes**: You need permissions beyond what Composio's default app has approved
14 -- **Custom instance**: Connecting to a self-hosted or regional variant (e.g., custom Salesforce subdomain)
15 -
16 -<Steps>
17 -<Step>
18 -<StepTitle>Check if a toolkit needs custom credentials</StepTitle>
19 -
20 -In the [Composio platform](https://platform.composio.dev), go to "All Toolkits" and select the toolkit. If it shows no Composio managed auth schemes, you'll need to create an auth config. You can also browse the full list on the [managed auth page](/toolkits/managed-auth).
21 -</Step>
22 -
23 -<Step>
24 -<StepTitle>Create an auth config</StepTitle>
25 -
26 -1. Go to **Authentication management** in the [dashboard](https://platform.composio.dev)
27 -2. Click **Create Auth Config**
28 -3. Select the toolkit
29 -4. Choose the auth scheme (OAuth2, API Key, etc.)
30 -5. Enter your credentials (client ID, client secret, API key, etc.)
31 -6. Click **Create**
32 -
33 -Copy the auth config ID (e.g., `ac_1234abcd`).
34 -
35 -<Callout type="info">
36 -Step-by-step guides for popular toolkits: [Google](https://composio.dev/auth/googleapps) | [GitHub](https://composio.dev/auth/github) | [Slack](https://composio.dev/auth/slack) | [HubSpot](https://composio.dev/auth/hubspot) | [All toolkits](https://composio.dev/auth)
37 -</Callout>
38 -</Step>
39 -
40 -<Step>
41 -<StepTitle>Use in your session</StepTitle>
42 -
43 -Pass your auth config ID when creating a session:
44 -
45 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
46 -<Tab value="Python">
47 -```python
48 -session = composio.create(
49 - user_id="user_123",
50 - auth_configs={
51 - "posthog": "ac_your_posthog_config"
52 - }
53 -)
54 -```
55 -</Tab>
56 -<Tab value="TypeScript">
57 -```typescript
58 -import { Composio } from '@composio/core';
59 -const composio = new Composio({ apiKey: 'your_api_key' });
60 -// ---cut---
61 -const session = await composio.create("user_123", {
62 - authConfigs: {
63 - posthog: "ac_your_posthog_config",
64 - },
65 -});
66 -```
67 -</Tab>
68 -</Tabs>
69 -
70 -Your session will now use this auth config when users connect to this toolkit.
71 -</Step>
72 -</Steps>
73 -
74 -## What to read next
75 -
76 -<Cards>
77 - <Card icon={<Key />} title="When to use your own developer credentials" href="/docs/custom-app-vs-managed-app" description="Decide when to use Composio managed auth and when to bring your own" />
78 - <Card icon={<Palette />} title="White-labeling authentication" href="/docs/white-labeling-authentication" description="Use your own OAuth apps so users see your branding on consent screens" />
79 - <Card icon={<Key />} title="Authentication overview" href="/docs/authentication" description="Connect Links, OAuth, API keys, and how Composio manages auth" />
80 - <Card icon={<Wrench />} title="Configuring sessions" href="/docs/configuring-sessions" description="Pass auth configs, connected accounts, and toolkit restrictions to sessions" />
81 -</Cards>
docs/content/docs/white-labeling-authentication.mdx
+7 -115
@@ -38,129 +38,21 @@ Customizing the Connect Link only changes the Composio-hosted page. For OAuth to
38
39 ## Using your own OAuth apps
40
41 -OAuth toolkits like Google and GitHub show a consent screen that says which app is requesting access. By default this reads "Composio wants to connect to your account." To show your app name instead, register your own OAuth app and tell Composio to use it. This is done by creating a [custom auth config](/docs/using-custom-auth-configuration) with your own credentials. See [when to use your own OAuth apps](#when-to-use-your-own-oauth-apps).
41 +OAuth toolkits like Google and GitHub show a consent screen that says which app is requesting access. By default this reads "Composio wants to connect to your account." To show your app name instead, create a custom auth config with your own OAuth credentials and pass that auth config when creating a session.
42
43 <Callout type="info" title="You don't need this for every toolkit">
44 Only white-label toolkits where users see a consent screen (Google, GitHub, Slack, etc.). Toolkits that use API keys don't show consent screens, so there's nothing to white-label. You can mix and match freely.
45 </Callout>
46
47 -<Steps>
48 -<Step>
49 -<StepTitle>Create an OAuth app in the toolkit's developer portal</StepTitle>
50 -
51 -Register a new OAuth app with the toolkit. Set the callback URL to:
52 -
53 -```
54 -https://backend.composio.dev/api/v3.1/toolkits/auth/callback
55 -```
56 -
57 -You'll get a **Client ID** and **Client Secret**.
58 -
59 -Step-by-step guides: [Google](https://composio.dev/auth/googleapps) | [Slack](https://composio.dev/auth/slack) | [HubSpot](https://composio.dev/auth/hubspot) | [All toolkits](https://composio.dev/auth)
60 -</Step>
61 -
62 -<Step>
63 -<StepTitle>Create an auth config in Composio</StepTitle>
64 -
65 -In the [Composio dashboard](https://platform.composio.dev):
66 -
67 -1. Go to **Authentication management** → **Create Auth Config**
68 -2. Select the toolkit (e.g., GitHub)
69 -3. Choose **OAuth2** scheme
70 -4. Toggle on **Use your own developer credentials**
71 -5. Enter your **Client ID** and **Client Secret**
72 -6. Click **Create**
73 -
74 -Copy the auth config ID (e.g., `ac_1234abcd`).
75 -
76 -</Step>
77 -
78 -<Step>
79 -<StepTitle>Pass the auth config ID in your session</StepTitle>
80 -
81 -Specify which toolkits should use your custom auth config. Any toolkit you don't specify here will use Composio's managed auth automatically:
82 -
83 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
84 -<Tab value="Python">
85 -```python
86 -session = composio.create(
87 - user_id="user_123",
88 - auth_configs={
89 - "github": "ac_your_github_config",
90 - "slack": "ac_your_slack_config",
91 - # gmail, linear, etc. use Composio managed auth automatically
92 - },
93 -)
94 -```
95 -</Tab>
96 -<Tab value="TypeScript">
97 -```typescript
98 -import { Composio } from '@composio/core';
99 -const composio = new Composio({ apiKey: 'your_api_key' });
100 -// ---cut---
101 -const session = await composio.create("user_123", {
102 - authConfigs: {
103 - github: "ac_your_github_config",
104 - slack: "ac_your_slack_config",
105 - // gmail, linear, etc. use Composio managed auth automatically
106 - },
107 -});
108 -```
109 -</Tab>
110 -</Tabs>
111 -
112 -Now when users connect GitHub or Slack, they'll see your app name on the consent screen. For Gmail and everything else, Composio's default app handles it.
113 -</Step>
114 -</Steps>
115 -
116 -### When to use your own OAuth apps
117 -
118 -- **Production apps** where end users see consent screens. They should see your brand, not Composio's.
119 -- **Enterprise customers** who require your branding end-to-end.
120 -- **Toolkits where you need custom scopes** beyond what Composio's default app provides.
121 -
122 -For development and testing, Composio's managed auth works fine. No OAuth app setup required.
47 +<Card icon={<Key />} title="Managed vs custom auth" href="/docs/custom-app-vs-managed-app" description="Decide when to use custom credentials, create an auth config, and pass it to sessions." />
48
49 ### Switching from Composio-managed to your own OAuth app
50
126 -Existing connected accounts are permanently tied to the auth config they were created with. Switching to a custom auth config does not affect them. You have two options:
127 -
128 -**Keep existing users as-is.** Just pass `authConfigs` for the toolkits you want to white-label. Users who already have a connection keep using it. Users who need to connect for the first time go through your OAuth app:
129 -
130 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
131 -<Tab value="Python">
132 -```python
133 -session = composio.create(
134 - user_id="user_123",
135 - auth_configs={
136 - "github": "ac_your_github_config", # new connections use your OAuth app
137 - },
138 -)
139 -# Existing GitHub connections for this user keep working as before.
140 -# Only new connections go through your custom OAuth app.
141 -```
142 -</Tab>
143 -<Tab value="TypeScript">
144 -```typescript
145 -import { Composio } from '@composio/core';
146 -const composio = new Composio({ apiKey: 'your_api_key' });
147 -// ---cut---
148 -const session = await composio.create("user_123", {
149 - authConfigs: {
150 - github: "ac_your_github_config", // new connections use your OAuth app
151 - },
152 -});
153 -// Existing GitHub connections for this user keep working as before.
154 -// Only new connections go through your custom OAuth app.
155 -```
156 -</Tab>
157 -</Tabs>
158 -
159 -<Callout type="warn">
160 -Existing users' connections continue using Composio's OAuth client credentials for token refresh until they re-authenticate.
161 -</Callout>
51 +Existing connected accounts are tied to the auth config they were created with. Switching to a custom auth config affects new connections for that toolkit; existing users keep using their current connected accounts until they re-authenticate or you import/migrate their credentials.
52
163 -**Fully migrate all users.** To move every user to your OAuth app, delete their old connected accounts and have them re-authenticate. There is no way to move an existing connection from one auth config to another without re-authentication.
53 +- To use the custom config for new connections, pass `authConfigs` when creating or updating the session.
54 +- Existing connections continue refreshing with their original auth config.
55 +- To fully migrate an existing user, delete the old connected account and have them re-authenticate with the new auth config, or import their credentials into the new config where supported.
56
57 ## Routing the callback through your domain
58
@@ -271,6 +163,6 @@ After authentication, Composio redirects the user to your callback URL instead o
163 ## What to read next
164
165 <Cards>
274 - <Card icon={<Key />} title="Using custom auth configuration" href="/docs/using-custom-auth-configuration" description="Set up auth configs for toolkits that don't have Composio managed authentication" />
166 + <Card icon={<Key />} title="Managed vs custom auth" href="/docs/custom-app-vs-managed-app" description="Set up auth configs for OAuth apps, API keys, and toolkits without managed auth" />
167 <Card icon={<Key />} title="Authentication overview" href="/docs/authentication" description="Connect Links, OAuth, API keys, and how Composio manages auth" />
168 </Cards>
docs/content/docs/workbench.mdx
+2 -2
@@ -4,7 +4,7 @@ description: A persistent Python sandbox for writing code, calling tools program
4 keywords: [workbench, sandbox, remote execution, bulk operations, data processing]
5 ---
6
7 -The workbench is a persistent Python sandbox where your agent can write and execute code. It has access to all Composio tools programmatically, plus helper functions for calling LLMs, uploading files, and making API requests. State persists across calls within a [session](/docs/users-and-sessions). The `COMPOSIO_REMOTE_BASH_TOOL` meta tool also runs commands in the same sandbox.
7 +The workbench is a persistent Python sandbox where your agent can write and execute code. It has access to all Composio tools programmatically, plus helper functions for calling LLMs, uploading files, and making API requests. State persists across calls within a [session](/docs/how-composio-works). The `COMPOSIO_REMOTE_BASH_TOOL` meta tool also runs commands in the same sandbox.
8
9 <Callout>
10 The workbench is part of the [meta tools](/docs/tools-and-toolkits#meta-tools) system. It's available when you create sessions, not when [executing tools directly](/docs/tools-direct/executing-tools).
@@ -80,7 +80,7 @@ The sandbox preserves variables and files across calls. The agent can paginate t
80 ## What to read next
81
82 <Cards>
83 - <Card icon={<Database />} title="Users & Sessions" href="/docs/users-and-sessions" description="How sessions scope tools, auth, and workbench state to a user" />
83 + <Card icon={<Database />} title="What is a session?" href="/docs/how-composio-works" description="How sessions scope tools, auth, and workbench state to a user" />
84 <Card icon={<Wrench />} title="Tools and toolkits" href="/docs/tools-and-toolkits" description="How meta tools discover, authenticate, and execute tools at runtime" />
85 <Card icon={<Zap />} title="Triggers" href="/docs/triggers" description="Event-driven payloads from connected apps" />
86 </Cards>
docs/mdx-components.tsx
+2
@@ -27,6 +27,7 @@ import { DocsHero } from '@/components/docs-hero';
27 import { Glossary, GlossaryTerm } from '@/components/glossary';
28 import { ApiBaseUrl } from '@/components/api-base-url';
29 import { ApiEndpointsTable } from '@/components/api-endpoints-table';
30 +import { ClaudeMockUI } from '@/components/claude-mock-ui';
31 import {
32 ShieldCheck,
33 Route as RouteIcon,
@@ -105,6 +106,7 @@ export function getMDXComponents(components?: MDXComponents): MDXComponents {
106 GlossaryTerm,
107 ApiBaseUrl,
108 ApiEndpointsTable,
109 + ClaudeMockUI,
110 // Lucide icons
111 ShieldCheck,
112 RouteIcon,
docs/next.config.mjs
+15 -5
@@ -86,7 +86,7 @@ const config = {
86 // Core concepts moved from tool-router to docs
87 {
88 source: '/tool-router/users-and-sessions',
89 - destination: '/docs/users-and-sessions',
89 + destination: '/docs/how-composio-works',
90 permanent: true,
91 },
92 {
@@ -122,12 +122,12 @@ const config = {
122 },
123 {
124 source: '/tool-router/using-custom-auth-configs',
125 - destination: '/docs/using-custom-auth-configuration',
125 + destination: '/docs/custom-app-vs-managed-app',
126 permanent: true,
127 },
128 {
129 source: '/docs/authenticating-users/using-custom-auth-configs',
130 - destination: '/docs/using-custom-auth-configuration',
130 + destination: '/docs/custom-app-vs-managed-app',
131 permanent: true,
132 },
133 {
@@ -256,9 +256,14 @@ const config = {
256 permanent: true,
257 },
258 // Features section redirects
259 + {
260 + source: '/docs/users-and-sessions',
261 + destination: '/docs/how-composio-works',
262 + permanent: true,
263 + },
264 {
265 source: '/docs/user-management',
261 - destination: '/docs/users-and-sessions#users',
266 + destination: '/docs/how-composio-works#users',
267 permanent: true,
268 },
269 {
@@ -726,9 +731,14 @@ const config = {
731 destination: '/docs/white-labeling-authentication',
732 permanent: true,
733 },
734 + {
735 + source: '/docs/using-custom-auth-configuration',
736 + destination: '/docs/custom-app-vs-managed-app',
737 + permanent: true,
738 + },
739 {
740 source: '/docs/guides/using-custom-auth-configuration',
731 - destination: '/docs/using-custom-auth-configuration',
741 + destination: '/docs/custom-app-vs-managed-app',
742 permanent: true,
743 },
744 {