@devries-cameron20 / composio-1 / commits / 5ca29e857
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: restore auth pages to the sidebar as an Authentication folder

PR #4099 dropped 8 auth pages from meta.json. That was a net win for machines (Loop 5 eval: 84/100 vs 77/100, tool-routing failure mode gone) but it made the pages unreachable by clicking. PostHog, weekday-matched and control-adjusted, shows the affected pages down 14-64pp beyond the site-wide baseline drift. Restore human navigation without touching the machine-facing wins: - authentication.mdx becomes authentication/index.mdx and the 7 sibling auth pages move into the folder. /docs/authentication keeps its URL (fumadocs serves index.mdx at the folder route), so Core concepts still shows one row and the top-level sidebar row count stays 20. - shared-connections moves into extending-sessions: it is experimental and is a session capability, not a core auth concept. - "Migration and security" splits into "Migration" and "Security and data" — separator headings, not clickable rows. - Drop AUTHENTICATION_GUIDE_URLS from app/llms.txt/route.ts. The pages are back in the page tree, so they emit automatically under Core concepts -> Authentication; the hardcoded list would now duplicate. - 8 permanent redirects for the old URLs (36-42% Google entry rate on most of them), plus existing redirect destinations repointed so none of them chain. - ~90 inbound links rewritten across content, api-overviews, app, lib and agent instructions. lint:links is the gate: 0 errors. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Kshitij Jhunjhunwala committed Aug 14, 2026 at 12:02 UTC 5ca29e857e24643c63e40acf9f2dc46e0fe9403d
60 files changed +198 -147
docs/agent/instructions/context.md
+5 -5
@@ -19,14 +19,14 @@ This is your always-on map of Composio's concepts and the canonical page for eac
19 ## Authentication
20
21 - **How auth works** — Composio uses Connect Links (hosted auth pages) and **auth configs** (per-toolkit blueprints) to create **connected accounts** (stored credentials) scoped to a userID. This is the page for "how does authentication work". → [Authentication](/docs/authentication)
22 -- **Auth schemes / modes** — a toolkit's auth config uses one of `OAUTH2`, `API_KEY`, `BEARER_TOKEN`, or `BASIC`. When you mention a toolkit's auth mode, link the reference rather than explaining it inline. → [Auth schemes](/reference/api-reference/auth-configs#auth-schemes) for what each mode is and when it's used, [Authentication](/docs/authentication) for how auth works overall, and [Managed vs custom auth](/docs/custom-app-vs-managed-app) for choosing or bringing your own scheme.
22 +- **Auth schemes / modes** — a toolkit's auth config uses one of `OAUTH2`, `API_KEY`, `BEARER_TOKEN`, or `BASIC`. When you mention a toolkit's auth mode, link the reference rather than explaining it inline. → [Auth schemes](/reference/api-reference/auth-configs#auth-schemes) for what each mode is and when it's used, [Authentication](/docs/authentication) for how auth works overall, and [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app) for choosing or bringing your own scheme.
23 - **In-chat auth** — the agent prompts the user to connect via `COMPOSIO_MANAGE_CONNECTIONS`. → [In-chat authentication](/docs/authenticating-users/in-chat-authentication)
24 - **Manual auth** — generate Connect Links yourself with `session.authorize()`. → [Manually authenticating users](/docs/authenticating-users/manually-authenticating)
25 -- **Managed vs custom auth** — use Composio's managed OAuth apps, or bring your own for branding/scopes. → [Managed vs custom auth](/docs/custom-app-vs-managed-app)
26 -- **White-labeling** — remove Composio branding from the auth flow. → [White-labeling authentication](/docs/white-labeling-authentication)
25 +- **Managed vs custom auth** — use Composio's managed OAuth apps, or bring your own for branding/scopes. → [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app)
26 +- **White-labeling** — remove Composio branding from the auth flow. → [White-labeling authentication](/docs/authentication/white-labeling-authentication)
27 - **Callback identity verification** — opt-in per-project defense against OAuth session fixation, documented in the connected-accounts API overview: set a verifier URL and Composio holds each OAuth connection until the developer's server confirms the returning user (`complete_auth`); once set it covers every OAuth connection in the project. This is the section for "connections from the dashboard stopped completing" and "a real `user_id` is now required". → [Callback identity verification](/reference/api-reference/connected-accounts#callback-identity-verification)
28 -- **Importing existing connections** — pass in API keys or bearer tokens you already hold. → [Importing existing connections](/docs/importing-existing-connections)
29 -- **Multiple accounts per user** — e.g. work and personal Gmail. → [Managing multiple connected accounts](/docs/managing-multiple-connected-accounts)
28 +- **Importing existing connections** — pass in API keys or bearer tokens you already hold. → [Importing existing connections](/docs/authentication/importing-existing-connections)
29 +- **Multiple accounts per user** — e.g. work and personal Gmail. → [Managing multiple connected accounts](/docs/authentication/managing-multiple-connected-accounts)
30 - **Shared connections** — share one connected account across users via an ACL. → [Shared connections](/docs/authenticating-users/shared-connections)
31
32 ## Triggers and webhooks
docs/api-overviews/auth-configs.mdx
+2 -2
@@ -8,7 +8,7 @@ Each auth config defines:
8 - **Scopes**: what your tools are allowed to do on the user's behalf
9 - **Credentials**: Composio's managed app, or your own OAuth client and secrets
10
11 -Reach for a custom auth config when you need your own branding on consent screens, custom scopes, a dedicated rate-limit quota, or a custom toolkit instance. See [managed vs custom auth](/docs/custom-app-vs-managed-app) for the decision and [how Composio handles authentication](/docs/authentication) for the full picture.
11 +Reach for a custom auth config when you need your own branding on consent screens, custom scopes, a dedicated rate-limit quota, or a custom toolkit instance. See [managed vs custom auth](/docs/authentication/custom-app-vs-managed-app) for the decision and [how Composio handles authentication](/docs/authentication) for the full picture.
12
13 ## Auth schemes
14
@@ -21,6 +21,6 @@ The `auth_scheme` on an auth config determines how users authenticate to the too
21 | `BEARER_TOKEN` | A bearer access token you already hold (for example, from your own OAuth flow). Composio sends it as `Authorization: Bearer <token>` and does not refresh it, so you keep it current. | Bringing an existing OAuth or server-to-server token into Composio, or apps that issue long-lived tokens. |
22 | `BASIC` | HTTP Basic authentication with a username and password. | Services that use Basic Auth. |
23
24 -Most OAuth toolkits work out of the box with Composio managed auth. For the others you supply the credential fields. To choose or customize the scheme, see [managed vs custom auth](/docs/custom-app-vs-managed-app).
24 +Most OAuth toolkits work out of the box with Composio managed auth. For the others you supply the credential fields. To choose or customize the scheme, see [managed vs custom auth](/docs/authentication/custom-app-vs-managed-app).
25
26 These endpoints use your project API key in the `x-api-key` header. Each auth config is addressed by its `nanoid`, and you can enable or disable one without deleting it.
docs/api-overviews/connected-accounts.mdx
+2 -2
@@ -2,7 +2,7 @@ A connected account is a single user's authorized connection to a toolkit. It st
2
3 Composio creates a connected account when a user completes the flow defined by an [auth config](/reference/api-reference/auth-configs). From there you manage its full lifecycle:
4
5 -- **Create or link**: start a new connection, or generate an auth link session for the user to authorize. See [manually authenticating users](/docs/manually-authenticating).
5 +- **Create or link**: start a new connection, or generate an auth link session for the user to authorize. See [manually authenticating users](/docs/authentication/manually-authenticating).
6 - **Refresh**: renew authentication for an account whose tokens have expired.
7 - **Enable, disable, or update**: change an account's status or metadata without removing it.
8 - **Revoke or delete**: revoke the grant at the provider, or remove the account from Composio.
@@ -13,7 +13,7 @@ Each account is addressed by its `nanoid`. List endpoints accept filters so you
13
14 A Composio Connect Link is a hosted, secure sign-in page. You create one with the create auth link session endpoint, redirect the user to the returned URL, and Composio handles the rest: the user signs in, Composio creates the connected account, and Composio stores and refreshes its tokens. Credentials never pass through your app. This works for all Composio managed connections, with no OAuth credentials to set up.
15
16 -By default a connected account is `PRIVATE` and usable only by its owning user. Mark one `SHARED` to let other users reach it through a per-connection access control list. See [shared connections](/docs/shared-connections).
16 +By default a connected account is `PRIVATE` and usable only by its owning user. Mark one `SHARED` to let other users reach it through a per-connection access control list. See [shared connections](/docs/extending-sessions/shared-connections).
17
18 These endpoints use your project API key in the `x-api-key` header.
19
docs/app/layout.tsx
+1 -1
@@ -13,7 +13,7 @@ const defaultLinkSlugs: { slug: string[]; source: typeof source }[] = [
13 { slug: ['quickstart'], source },
14 { slug: ['authentication'], source },
15 { slug: ['configuring-sessions'], source },
16 - { slug: ['white-labeling-authentication'], source },
16 + { slug: ['authentication', 'white-labeling-authentication'], source },
17 { slug: ['glossary'], source: referenceSource },
18 { slug: ['troubleshooting'], source },
19 ];
docs/app/llms.mdx/[[...slug]]/route.ts
+1 -1
@@ -946,7 +946,7 @@ async function generateManagedAuthIndex(): Promise<string> {
946 " -H 'x-api-key: YOUR_API_KEY'",
947 '```',
948 '',
949 - 'See [When to use your own developer credentials](/docs/custom-app-vs-managed-app.md) for help deciding which approach fits your use case.',
949 + 'See [When to use your own developer credentials](/docs/authentication/custom-app-vs-managed-app.md) for help deciding which approach fits your use case.',
950 '',
951 `## Composio Managed App Available (${managed.length})`,
952 '',
docs/app/llms.txt/route.ts
-15
@@ -100,17 +100,6 @@ function formatPage(page: { url: string }) {
100 return `- https://docs.composio.dev${page.url}.md`;
101 }
102
103 -const AUTHENTICATION_GUIDE_URLS = [
104 - '/docs/manually-authenticating',
105 - '/docs/managing-multiple-connected-accounts',
106 - '/docs/shared-connections',
107 - '/docs/importing-existing-connections',
108 - '/docs/custom-app-vs-managed-app',
109 - '/docs/programmatic-auth-configs',
110 - '/docs/controlling-scopes',
111 - '/docs/white-labeling-authentication',
112 -];
113 -
103 /**
104 * Splits reference pages by REST version.
105 *
@@ -165,10 +154,6 @@ ${legacyReferencePages.map(formatPage).join('\n')}
154
155 ${docsTree}
156
168 -## Authentication guides
169 -
170 -${AUTHENTICATION_GUIDE_URLS.map(url => formatPage({ url })).join('\n')}
171 -
157 ## Examples
158
159 ${examplesPages.map(formatPage).join('\n')}
docs/content/changelog/03-13-26-polling-interval-grace-period.mdx
+1 -1
@@ -28,4 +28,4 @@ Set up **your own OAuth app**. With custom auth:
28 OAuth approval from Google, Microsoft, etc. takes **days to weeks**. Start now.
29 </Callout>
30
31 -→ [Set up your own OAuth app](/docs/custom-app-vs-managed-app)
\ No newline at end of file
31 +→ [Set up your own OAuth app](/docs/authentication/custom-app-vs-managed-app)
\ No newline at end of file
docs/content/changelog/04-07-26-bearer-token-patch.mdx
+1 -1
@@ -22,7 +22,7 @@ BEARER_TOKEN is injected as an alternative scheme alongside OAuth2, so existing
22 Creating bearer token auth configs is currently available only via API and SDK — not yet supported in the dashboard UI.
23 </Callout>
24
25 -See the [importing connections guide](/docs/importing-existing-connections) for full examples.
25 +See the [importing connections guide](/docs/authentication/importing-existing-connections) for full examples.
26
27 ## Credential Patching
28
docs/content/changelog/04-09-26-multi-account-aliases.mdx
+1 -1
@@ -45,4 +45,4 @@ await composio.connectedAccounts.update('ca_abc123', { alias: 'work-gmail' });
45
46 Aliases must be unique per user and toolkit within a project.
47
48 -See the [multi-account guide](/docs/managing-multiple-connected-accounts) for full details.
48 +See the [multi-account guide](/docs/authentication/managing-multiple-connected-accounts) for full details.
docs/content/changelog/04-28-26-sdk-link-allow-multiple.mdx
+1 -1
@@ -52,7 +52,7 @@ const connectionRequest = await composio.connectedAccounts.link(
52 </Tab>
53 </Tabs>
54
55 -Pair with a session-level `multiAccount` / `multi_account` config so the agent can disambiguate at execution time. See [Managing multiple connected accounts](/docs/managing-multiple-connected-accounts) for the session shape.
55 +Pair with a session-level `multiAccount` / `multi_account` config so the agent can disambiguate at execution time. See [Managing multiple connected accounts](/docs/authentication/managing-multiple-connected-accounts) for the session shape.
56
57 **2. You're migrating from `initiate()` to `link()`** as part of the [Composio-managed OAuth migration](/docs/changelog/2026/04/24). Pass `allow_multiple` / `allowMultiple` through unchanged — same flag name, same default (`False`), same exception (`ComposioMultipleConnectedAccountsError`).
58
docs/content/changelog/05-08-26-session-use-update-connected-accounts.mdx
+1 -1
@@ -101,7 +101,7 @@ const session = await composio.create("user_123", {
101 </Tab>
102 </Tabs>
103
104 -Only one account per toolkit is allowed when [multi-account mode](/docs/managing-multiple-connected-accounts) is disabled.
104 +Only one account per toolkit is allowed when [multi-account mode](/docs/authentication/managing-multiple-connected-accounts) is disabled.
105
106 ### SDK versions
107
docs/content/docs/auth-configuration/connected-accounts.mdx
+2 -2
@@ -7,7 +7,7 @@ legacy: true
7 ---
8
9 <Callout type="info">
10 -If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. See [Managing multiple connected accounts](/docs/managing-multiple-connected-accounts) for how sessions handle account selection automatically.
10 +If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. See [Managing multiple connected accounts](/docs/authentication/managing-multiple-connected-accounts) for how sessions handle account selection automatically.
11 </Callout>
12
13 Connected accounts are authenticated connections between your users and toolkits. After users authenticate (see [Authenticating tools](/docs/tools-direct/authenticating-tools)), you can manage these accounts throughout their lifecycle.
@@ -319,7 +319,7 @@ try {
319 </Tabs>
320
321 <Callout type="info">
322 -For session-based apps, see [Managing multiple connected accounts](/docs/managing-multiple-connected-accounts) for how to pass a specific account to a session.
322 +For session-based apps, see [Managing multiple connected accounts](/docs/authentication/managing-multiple-connected-accounts) for how to pass a specific account to a session.
323 </Callout>
324
325 ### Execute with a specific account
docs/content/docs/auth-configuration/custom-auth-configs.mdx
+1 -1
@@ -7,7 +7,7 @@ legacy: true
7 ---
8
9 <Callout type="info">
10 -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 +If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. See [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app) for how to use custom credentials with sessions.
11 </Callout>
12
13 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/auth-configuration/custom-auth-params.mdx
+1 -1
@@ -7,7 +7,7 @@ legacy: true
7 ---
8
9 <Callout type="info">
10 -If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. Sessions handle authentication automatically via [in-chat authentication](/docs/authentication#in-chat-authentication) or [manual authentication](/docs/manually-authenticating).
10 +If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. Sessions handle authentication automatically via [in-chat authentication](/docs/authentication#in-chat-authentication) or [manual authentication](/docs/authentication/manually-authenticating).
11 </Callout>
12
13 If you already manage OAuth tokens or API keys yourself and want Composio to execute tools using your credentials, you can pass them directly at execution time — no connected account or redirect flow required.
docs/content/docs/auth-configuration/white-labeling.mdx
+1 -1
@@ -7,7 +7,7 @@ legacy: true
7 ---
8
9 <Callout type="info">
10 -If you're building an agent with sessions, see [White-labeling authentication](/docs/white-labeling-authentication) instead.
10 +If you're building an agent with sessions, see [White-labeling authentication](/docs/authentication/white-labeling-authentication) instead.
11 </Callout>
12
13 There are four places where Composio branding shows up during authentication:
docs/content/docs/authentication/controlling-scopes.mdx renamed
+1 -1
@@ -150,4 +150,4 @@ const session = await composio.create('user_123', {
150
151 ## Next
152
153 -<Card icon={<Palette />} title="White-labeling authentication" href="/docs/white-labeling-authentication" description="Remove Composio branding from your auth flows" />
153 +<Card icon={<Palette />} title="White-labeling authentication" href="/docs/authentication/white-labeling-authentication" description="Remove Composio branding from your auth flows" />
docs/content/docs/authentication/custom-app-vs-managed-app.mdx renamed
+3 -3
@@ -17,7 +17,7 @@ Managed apps are the default. Every toolkit that supports OAuth has a Composio m
17
18 - **You're building and iterating.** No OAuth app registration, no credentials to manage. Create a session and start testing immediately.
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.
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/authentication/white-labeling-authentication#customizing-the-connect-link) with your logo and app title without needing your own OAuth app.
21
22 ## When to use a custom auth config
23
@@ -34,7 +34,7 @@ Bring your own credentials when any of these apply:
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 -The steps below use the dashboard. To create auth configs in code instead, for example one per customer, see [Programmatic auth configs](/docs/programmatic-auth-configs).
37 +The steps below use the dashboard. To create auth configs in code instead, for example one per customer, see [Programmatic auth configs](/docs/authentication/programmatic-auth-configs).
38
39 <Steps>
40 <Step>
@@ -142,4 +142,4 @@ Some toolkits don't have Composio managed auth. For these, the setup is the same
142
143 ## Next
144
145 -<Card icon={<Code />} title="Programmatic auth configs" href="/docs/programmatic-auth-configs" description="Create auth configs in code and pass them to a session" />
145 +<Card icon={<Code />} title="Programmatic auth configs" href="/docs/authentication/programmatic-auth-configs" description="Create auth configs in code and pass them to a session" />
docs/content/docs/authentication/importing-existing-connections.mdx renamed
+3 -3
@@ -17,7 +17,7 @@ This is useful when:
17
18 ## Prerequisites
19
20 -1. **An [auth config](/docs/programmatic-auth-configs)** for the toolkit you're importing into
20 +1. **An [auth config](/docs/authentication/programmatic-auth-configs)** for the toolkit you're importing into
21 2. **The existing credentials** for each user (API keys, bearer tokens, username/password, etc.)
22 3. **A userID** for each user. Any string that uniquely identifies them in your system.
23
@@ -74,7 +74,7 @@ If you manage your own OAuth flow and already have an access token for a service
74
75 Since you're providing your own token, Composio won't handle OAuth refresh. You're responsible for refreshing the token on your end and pushing the updated value to Composio via the [PATCH method](#updating-credentials) whenever it changes.
76
77 -After [creating an auth config](/docs/programmatic-auth-configs) with `authScheme: "BEARER_TOKEN"`, use the snippet below to create a connected account:
77 +After [creating an auth config](/docs/authentication/programmatic-auth-configs) with `authScheme: "BEARER_TOKEN"`, use the snippet below to create a connected account:
78
79 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
80 <Tab value="Python">
@@ -326,4 +326,4 @@ const session = await composio.create('user_123', {
326
327 ## Next
328
329 -<Card icon={<Database />} title="Managing multiple accounts" href="/docs/managing-multiple-connected-accounts" description="Pin and select connected accounts for a user" />
329 +<Card icon={<Database />} title="Managing multiple accounts" href="/docs/authentication/managing-multiple-connected-accounts" description="Pin and select connected accounts for a user" />
docs/content/docs/authentication/index.mdx renamed
+11 -11
@@ -29,7 +29,7 @@ Every session includes the [`COMPOSIO_MANAGE_CONNECTIONS`](/toolkits/meta-tools/
29
30 The user signs in on the hosted link and Composio stores the resulting connected account. Credentials never pass through your app or the model, so it's safe to surface the link right in the chat.
31
32 -You only need a [custom auth config](/docs/custom-app-vs-managed-app) to bring your own OAuth app, request specific scopes, or use a toolkit without managed auth.
32 +You only need a [custom auth config](/docs/authentication/custom-app-vs-managed-app) to bring your own OAuth app, request specific scopes, or use a toolkit without managed auth.
33
34 ## In-chat authentication
35
@@ -83,7 +83,7 @@ const session = await composio.create("user_123", {
83
84 Don't want to wait for the agent? Call `session.authorize()` to generate a Connect Link on demand, for onboarding, a settings page, or a pre-flight check before a task.
85
86 -<Card icon={<ShieldCheck />} title="Manual auth management" href="/docs/manually-authenticating">
86 +<Card icon={<ShieldCheck />} title="Manual auth management" href="/docs/authentication/manually-authenticating">
87 `session.authorize()`, callback URLs, connection status, and disabling in-chat prompts
88 </Card>
89
@@ -95,7 +95,7 @@ Composio manages authentication with **auth configs**. An [auth config](/referen
95 - **Scopes**: what actions your tools can perform
96 - **Credentials**: your own app credentials, or Composio's managed auth
97
98 -Composio creates one auth config per toolkit and applies it to every user who connects that toolkit. Most toolkits use Composio managed auth, so you don't create or configure anything. You only need a [custom auth config](/docs/custom-app-vs-managed-app) to use your own OAuth app or customize scopes.
98 +Composio creates one auth config per toolkit and applies it to every user who connects that toolkit. Most toolkits use Composio managed auth, so you don't create or configure anything. You only need a [custom auth config](/docs/authentication/custom-app-vs-managed-app) to use your own OAuth app or customize scopes.
99
100 <AuthConfigFlow />
101
@@ -136,12 +136,12 @@ console.log(connectionRequest.redirectUrl);
136 ## Authentication guides
137
138 <Cards>
139 - <Card title="Manual auth management" href="/docs/manually-authenticating" description="Generate Connect Links yourself, check connection status, and disable in-chat prompts." />
140 - <Card title="Multiple connected accounts" href="/docs/managing-multiple-connected-accounts" description="Let one user choose between work, personal, or other accounts." />
141 - <Card title="Shared connections" href="/docs/shared-connections" description="Share one connected account with a controlled set of users." />
142 - <Card title="Import existing connections" href="/docs/importing-existing-connections" description="Bring credentials your application already stores into Composio." />
143 - <Card title="Managed vs custom auth" href="/docs/custom-app-vs-managed-app" description="Decide whether to use Composio credentials or your own OAuth app." />
144 - <Card title="Programmatic auth configs" href="/docs/programmatic-auth-configs" description="Create auth configs in code and attach them to sessions." />
145 - <Card title="Control OAuth scopes" href="/docs/controlling-scopes" description="Choose the permissions requested when a user connects." />
146 - <Card title="White-label authentication" href="/docs/white-labeling-authentication" description="Use your own OAuth app and remove Composio branding." />
139 + <Card title="Manual auth management" href="/docs/authentication/manually-authenticating" description="Generate Connect Links yourself, check connection status, and disable in-chat prompts." />
140 + <Card title="Multiple connected accounts" href="/docs/authentication/managing-multiple-connected-accounts" description="Let one user choose between work, personal, or other accounts." />
141 + <Card title="Shared connections" href="/docs/extending-sessions/shared-connections" description="Share one connected account with a controlled set of users." />
142 + <Card title="Import existing connections" href="/docs/authentication/importing-existing-connections" description="Bring credentials your application already stores into Composio." />
143 + <Card title="Managed vs custom auth" href="/docs/authentication/custom-app-vs-managed-app" description="Decide whether to use Composio credentials or your own OAuth app." />
144 + <Card title="Programmatic auth configs" href="/docs/authentication/programmatic-auth-configs" description="Create auth configs in code and attach them to sessions." />
145 + <Card title="Control OAuth scopes" href="/docs/authentication/controlling-scopes" description="Choose the permissions requested when a user connects." />
146 + <Card title="White-label authentication" href="/docs/authentication/white-labeling-authentication" description="Use your own OAuth app and remove Composio branding." />
147 </Cards>
docs/content/docs/authentication/managing-multiple-connected-accounts.mdx renamed
+1 -1
@@ -220,4 +220,4 @@ for (const toolkit of toolkits.items) {
220
221 ## Next
222
223 -<Card icon={<Database />} title="Shared connections" href="/docs/shared-connections" description="Make one connected account usable by multiple users with a per-user access control list" />
223 +<Card icon={<Database />} title="Shared connections" href="/docs/extending-sessions/shared-connections" description="Make one connected account usable by multiple users with a per-user access control list" />
docs/content/docs/authentication/manually-authenticating.mdx renamed
+1 -1
@@ -215,4 +215,4 @@ console.log("All toolkits connected!");
215
216 ## Next
217
218 -<Card icon={<Database />} title="Managing multiple connected accounts" href="/docs/managing-multiple-connected-accounts" description="Let a user connect work and personal accounts for the same toolkit, then pick which one runs" />
218 +<Card icon={<Database />} title="Managing multiple connected accounts" href="/docs/authentication/managing-multiple-connected-accounts" description="Let a user connect work and personal accounts for the same toolkit, then pick which one runs" />
docs/content/docs/authentication/meta.json new
+13
@@ -0,0 +1,13 @@
1 +{
2 + "title": "Authentication",
3 + "pages": [
4 + "index",
5 + "manually-authenticating",
6 + "managing-multiple-connected-accounts",
7 + "importing-existing-connections",
8 + "custom-app-vs-managed-app",
9 + "programmatic-auth-configs",
10 + "controlling-scopes",
11 + "white-labeling-authentication"
12 + ]
13 +}
docs/content/docs/authentication/programmatic-auth-configs.mdx renamed
+2 -2
@@ -95,7 +95,7 @@ const authConfig = await composio.authConfigs.create('notion', {
95 </Tabs>
96
97 <Callout type="info">
98 -Omit `oauth_redirect_uri` to use Composio's default callback. Set it only when you [route the callback through your own domain](/docs/white-labeling-authentication#routing-the-callback-through-your-domain).
98 +Omit `oauth_redirect_uri` to use Composio's default callback. Set it only when you [route the callback through your own domain](/docs/authentication/white-labeling-authentication#routing-the-callback-through-your-domain).
99 </Callout>
100
101 ## Other auth types
@@ -211,4 +211,4 @@ console.log(fields);
211
212 ## Next
213
214 -<Card icon={<Key />} title="Controlling scopes" href="/docs/controlling-scopes" description="Override the default OAuth scopes Composio requests for a toolkit" />
214 +<Card icon={<Key />} title="Controlling scopes" href="/docs/authentication/controlling-scopes" description="Override the default OAuth scopes Composio requests for a toolkit" />
docs/content/docs/authentication/white-labeling-authentication.mdx renamed
+4 -4
@@ -22,7 +22,7 @@ To replace it with your own branding:
22 1. Go to **Project Settings** → [**Auth Screen**](https://dashboard.composio.dev/~/project/settings/auth-screen?utm_source=docs&utm_medium=content&utm_campaign=docs-white-labeling-authentication)
23 2. Upload your **Logo** and set your **App Title**
24
25 -This applies to all Connect Link flows across all toolkits, for both [in-chat](/docs/authentication#in-chat-authentication) and [manual](/docs/manually-authenticating) authentication. Each project has one logo and app title, so if you need different branding per product, use separate projects.
25 +This applies to all Connect Link flows across all toolkits, for both [in-chat](/docs/authentication#in-chat-authentication) and [manual](/docs/authentication/manually-authenticating) authentication. Each project has one logo and app title, so if you need different branding per product, use separate projects.
26
27 <Callout>
28 Customizing the Connect Link only changes the Composio-hosted page. For OAuth toolkits like Gmail, Google Sheets, GitHub, and Slack, users still see a consent screen saying "Composio wants to access your account." To change that, and to remove the "Secured by Composio" badge, set up your own OAuth app as described [below](#using-your-own-oauth-apps).
@@ -42,7 +42,7 @@ OAuth toolkits like Google and GitHub show a consent screen that says which app
42 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.
43 </Callout>
44
45 -<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." />
45 +<Card icon={<Key />} title="Managed vs custom auth" href="/docs/authentication/custom-app-vs-managed-app" description="Decide when to use custom credentials, create an auth config, and pass it to sessions." />
46
47 ### Switching from Composio-managed to your own OAuth app
48
@@ -150,8 +150,8 @@ const connectionRequest = await session.authorize("gmail", {
150 </Tab>
151 </Tabs>
152
153 -After authentication, Composio redirects the user to your callback URL instead of the default success page. For full details on the parameters appended to your callback URL, see [Manually authenticating users → Redirecting users after authentication](/docs/manually-authenticating#redirecting-users-after-authentication).
153 +After authentication, Composio redirects the user to your callback URL instead of the default success page. For full details on the parameters appended to your callback URL, see [Manually authenticating users → Redirecting users after authentication](/docs/authentication/manually-authenticating#redirecting-users-after-authentication).
154
155 ## Next
156
157 -<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" />
157 +<Card icon={<Key />} title="Managed vs custom auth" href="/docs/authentication/custom-app-vs-managed-app" description="Set up auth configs for OAuth apps, API keys, and toolkits without managed auth" />
docs/content/docs/configuring-sessions.mdx
+4 -4
@@ -441,7 +441,7 @@ Requires `@composio/core` ≥ `0.9.0` (TypeScript) or `composio` ≥ `0.13.0`
441
442 <Callout type="info">
443 `preload.tools` is not supported when `multiAccount.enable` is true. See
444 -[Managing multiple connected accounts](/docs/managing-multiple-connected-accounts).
444 +[Managing multiple connected accounts](/docs/authentication/managing-multiple-connected-accounts).
445 </Callout>
446
447 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
@@ -536,7 +536,7 @@ const session = await composio.create("user_123", {
536 </Tab>
537 </Tabs>
538
539 -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.
539 +See [White-labeling authentication](/docs/authentication/white-labeling-authentication) for branding, or [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app) for toolkits that require your own credentials.
540
541 ## Account selection
542
@@ -570,7 +570,7 @@ const session = await composio.create("user_123", {
570 </Tabs>
571
572 <Callout type="info">
573 -Arrays are the preferred format for `connectedAccounts`. A single string (e.g. `"ca_work_gmail"`) is still accepted for backwards compatibility and is automatically coerced to a single-element array. Only one account per toolkit is allowed when [multi-account mode](/docs/managing-multiple-connected-accounts) is disabled.
573 +Arrays are the preferred format for `connectedAccounts`. A single string (e.g. `"ca_work_gmail"`) is still accepted for backwards compatibility and is automatically coerced to a single-element array. Only one account per toolkit is allowed when [multi-account mode](/docs/authentication/managing-multiple-connected-accounts) is disabled.
574 </Callout>
575
576 ### Precedence
@@ -731,7 +731,7 @@ const connectedAccount = await connectionRequest.waitForConnection();
731 </Tab>
732 </Tabs>
733
734 -For more details, see [Manually authenticating users](/docs/manually-authenticating).
734 +For more details, see [Manually authenticating users](/docs/authentication/manually-authenticating).
735
736 ### toolkits()
737
docs/content/docs/extending-sessions/custom-mcp.mdx
+1 -1
@@ -409,5 +409,5 @@ See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for more example
409 <Card title="Using sessions via MCP" href="/docs/sessions-via-mcp" description="Connect an MCP client to a Composio-hosted session" />
410 <Card title="Custom Tools and Toolkits" href="/docs/extending-sessions/custom-tools-and-toolkits" description="Run your own tools inside your application process" />
411 <Card title="Configuring Sessions" href="/docs/configuring-sessions" description="Configure toolkit and tool filtering" />
412 -<Card title="Managing Multiple Connected Accounts" href="/docs/managing-multiple-connected-accounts" description="Select a connected account explicitly" />
412 +<Card title="Managing Multiple Connected Accounts" href="/docs/authentication/managing-multiple-connected-accounts" description="Select a connected account explicitly" />
413 </Cards>
docs/content/docs/extending-sessions/meta.json
+1
@@ -4,6 +4,7 @@
4 "pages": [
5 "proxy-execute",
6 "custom-tools-and-toolkits",
7 + "shared-connections",
8 "custom-mcp"
9 ]
10 }
docs/content/docs/extending-sessions/proxy-execute.mdx
+1 -1
@@ -101,7 +101,7 @@ Don't set the `Authorization` header yourself through `parameters`. Composio inj
101 | Status | Typical cause | How to resolve |
102 |---|---|---|
103 | `400 Bad Request` | Malformed endpoint path, invalid body, or unsupported `method`. | Check the upstream API docs for the expected shape. The proxy doesn't validate upstream schemas. |
104 -| `401 Unauthorized` | The connected account's token expired or was revoked. | Re-authenticate the user, or [import fresh credentials](/docs/importing-existing-connections). |
104 +| `401 Unauthorized` | The connected account's token expired or was revoked. | Re-authenticate the user, or [import fresh credentials](/docs/authentication/importing-existing-connections). |
105 | `403 Forbidden` | The user's OAuth scopes or API key don't cover this endpoint. | Update the [auth config scopes](/docs/auth-configuration/custom-auth-configs) and have the user re-consent. |
106 | `429 Too Many Requests` | Upstream rate limit (GitHub, Google, and so on). | Honor the `Retry-After` header and back off. Composio doesn't retry automatically. |
107
docs/content/docs/extending-sessions/shared-connections.mdx renamed
docs/content/docs/how-composio-works.mdx
+2 -2
@@ -58,7 +58,7 @@ A user is an identifier from your app. Composio stores connections under that ID
58 </Accordion>
59 </Accordions>
60
61 -A user can connect multiple accounts for the same toolkit, like work and personal Gmail. Use the same userID, then select the connected account when a session needs a specific one. See [Managing multiple connected accounts](/docs/managing-multiple-connected-accounts).
61 +A user can connect multiple accounts for the same toolkit, like work and personal Gmail. Use the same userID, then select the connected account when a session needs a specific one. See [Managing multiple connected accounts](/docs/authentication/managing-multiple-connected-accounts).
62
63 ## Meta tools
64
@@ -76,7 +76,7 @@ When a tool needs a connection, the session generates a Connect Link with `sessi
76
77 In chat, the agent can pause, ask the user to connect an app, then retry the tool once auth completes. Composio manages the OAuth redirects, token exchange, and refresh. Once a user connects a toolkit, the connected account persists and future sessions reuse it without re-authentication.
78
79 -For OAuth toolkits, Composio uses [managed apps](/docs/custom-app-vs-managed-app) by default. Bring your own app when you need your own branding, scopes, or consent screen.
79 +For OAuth toolkits, Composio uses [managed apps](/docs/authentication/custom-app-vs-managed-app) by default. Bring your own app when you need your own branding, scopes, or consent screen.
80
81 ## Sandbox
82
docs/content/docs/meta.json
+2 -1
@@ -22,8 +22,9 @@
22 "sessions-vs-direct-execution",
23 "tools-direct",
24 "auth-configuration",
25 - "---Migration and security---",
25 + "---Migration---",
26 "migration-guide",
27 + "---Security and data---",
28 "security"
29 ]
30 }
docs/content/docs/migration-guide/direct-to-sessions.mdx
+2 -2
@@ -264,7 +264,7 @@ const session = await composio.create("user_123", {
264 </Tab>
265 </Tabs>
266
267 -If you don't specify, the most recently connected account is used. See [Managing multiple connected accounts](/docs/managing-multiple-connected-accounts) for details.
267 +If you don't specify, the most recently connected account is used. See [Managing multiple connected accounts](/docs/authentication/managing-multiple-connected-accounts) for details.
268
269 ## Triggers
270
@@ -276,7 +276,7 @@ See [Triggers](/docs/triggers) for setup instructions.
276
277 If you've set up white-labeled OAuth screens with custom auth configs, those carry over automatically. Just pass the same auth config IDs to your session via `auth_configs` / `authConfigs`. Your users will continue to see your branding on consent screens.
278
279 -See [White-labeling authentication](/docs/white-labeling-authentication) for more.
279 +See [White-labeling authentication](/docs/authentication/white-labeling-authentication) for more.
280
281 ## Next
282
docs/content/docs/migration-guide/mcp-servers-to-sessions.mdx
+2 -2
@@ -238,11 +238,11 @@ const result = await session.execute("GITHUB_CREATE_ISSUE", {
238 session once and keep using it across calls; see [Configuring Sessions](/docs/configuring-sessions).
239 - **Sharing one account across users** — sessions support **shared connections**
240 (`account_type:"SHARED"` + an allow/deny ACL), pinned per session. See
241 - [Shared connections](/docs/shared-connections).
241 + [Shared connections](/docs/extending-sessions/shared-connections).
242 - **Tenant-specific params** (SharePoint sub-site, Jira subdomain) — prefill them via shared
243 credentials on the auth config.
244 - **White-labeling carries over** — pass the same white-labeled auth config IDs; users keep seeing
245 - your branding on consent screens. See [White-labeling authentication](/docs/white-labeling-authentication).
245 + your branding on consent screens. See [White-labeling authentication](/docs/authentication/white-labeling-authentication).
246 - **Triggers** — unchanged; continue using `composio.triggers.*` and webhooks (triggers aren't part
247 of sessions yet).
248 - **Dashboard** — sessions are created via the SDK. For no-code, personal app connections, use
docs/content/docs/migration-guide/new-sdk.mdx
+1 -1
@@ -736,7 +736,7 @@ console.log(authConfig);
736 </Tab>
737 </Tabs>
738
739 -For using custom authentication credentials, refer to the [Programmatic Auth Configs](/docs/programmatic-auth-configs) documentation.
739 +For using custom authentication credentials, refer to the [Programmatic Auth Configs](/docs/authentication/programmatic-auth-configs) documentation.
740
741 <Callout type="info">
742 The callback URL for creating custom OAuth configs is now `https://backend.composio.dev/api/v3/toolkits/auth/callback`. The previous URL was `https://backend.composio.dev/api/v1/auth-apps/add`.
docs/content/docs/sessions-vs-direct-execution.mdx
+1 -1
@@ -17,7 +17,7 @@ Use sessions unless you need full control over which tools are available and whe
17 | **Context cost** | Only meta tools in context, app tools loaded on demand | Every tool schema you select is loaded upfront |
18 | **Guidance** | Search returns recommended steps and common pitfalls alongside schemas | You get tool schemas only |
19 | **Memory** | Meta tools share context across calls, storing discovered IDs and relationships | You manage state between calls |
20 -| **Auth** | [In-chat](/docs/authentication#in-chat-authentication): agent prompts the user to connect when needed. Also supports [manual](/docs/manually-authenticating) | You build the auth flow with [connect links](/docs/tools-direct/authenticating-tools) |
20 +| **Auth** | [In-chat](/docs/authentication#in-chat-authentication): agent prompts the user to connect when needed. Also supports [manual](/docs/authentication/manually-authenticating) | You build the auth flow with [connect links](/docs/tools-direct/authenticating-tools) |
21 | **[Sandbox](/docs/sandbox/remote)** | Built in, large responses offloaded automatically | Not available |
22 | **Human approval** | You configure approval rules on the session. Harder to intercept individual calls since tools are discovered dynamically | You intercept before each call in your code |
23 | **Latency** | Multiple LLM turns (search, then execute) | Single call |
docs/content/docs/tools-direct/authenticating-tools.mdx
+2 -2
@@ -7,7 +7,7 @@ legacy: true
7 ---
8
9 <Callout type="info">
10 -If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. Sessions handle authentication automatically via [in-chat authentication](/docs/authentication#in-chat-authentication) or [manual authentication](/docs/manually-authenticating).
10 +If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. Sessions handle authentication automatically via [in-chat authentication](/docs/authentication#in-chat-authentication) or [manual authentication](/docs/authentication/manually-authenticating).
11 </Callout>
12
13 The first step in authenticating your users is to create an **Auth Config**. Every toolkit has its own authentication method such as `OAuth`, `API key`, `Basic Auth`, or custom schemes.
@@ -80,7 +80,7 @@ You should create multiple auth configs for the same toolkit when you need:
80 - **Different permission levels** - Limiting actions for specific use cases
81
82 <Cards>
83 - <Card title="Programmatic creation" href="/docs/programmatic-auth-configs">
83 + <Card title="Programmatic creation" href="/docs/authentication/programmatic-auth-configs">
84 For managing auth configs across multiple projects, you can create them programmatically via the API
85 </Card>
86 <Card title="Production white-labeling" href="/docs/auth-configuration/white-labeling">
docs/content/examples/general-agent-with-pi.mdx
+2 -2
@@ -46,7 +46,7 @@ bun add @composio/core @composio/experimental @earendil-works/pi-coding-agent
46
47 ## Install the bot
48
49 -A Slack bot needs a Slack app to authenticate as and a stream of events. Composio gives you both, so you never register a webhook with Slack or hold a bot token. The `slackbot` toolkit ships with Composio-managed OAuth, and you install it as one **[shared connection](/docs/shared-connections)** for the whole workspace.
49 +A Slack bot needs a Slack app to authenticate as and a stream of events. Composio gives you both, so you never register a webhook with Slack or hold a bot token. The `slackbot` toolkit ships with Composio-managed OAuth, and you install it as one **[shared connection](/docs/extending-sessions/shared-connections)** for the whole workspace.
50
51 This is `install.ts`, run once, built up three steps at a time:
52
@@ -106,5 +106,5 @@ Run `bun install.ts` once to set up the bot, start the server with `bun bot.ts`,
106
107 <Cards>
108 <Card title="Configuring sessions" href="/docs/configuring-sessions" description="Everything a session can scope: toolkits, tools, connections, and limits" />
109 - <Card title="Shared connections" href="/docs/shared-connections" description="SHARED vs PRIVATE accounts and the per-user ACL" />
109 + <Card title="Shared connections" href="/docs/extending-sessions/shared-connections" description="SHARED vs PRIVATE accounts and the per-user ACL" />
110 </Cards>
docs/content/examples/standup-slackbot.mdx
+6 -6
@@ -27,8 +27,8 @@ This is a deliberately advanced, opinionated build. It's a strong reference for
27
28 - **Background-agent sessions**: the draft agent runs on a schedule, not in a conversation. It works from the tools a member already connected and never pauses to ask for auth.
29 - **Manual execution for deterministic workflows**: outside the draft, the bot doesn't let an agent decide. It runs a fixed flow, calling tools directly with [manual execution](/docs/tools-direct/executing-tools), so a button always triggers the same exact steps.
30 -- **Manual, pre-connected auth**: members connect their tools ahead of time using [manual connections](/docs/manually-authenticating), and the agent just uses whatever is there.
31 -- **White-labelling** (advanced): your own Slack app and bot identity, via [white-labelling](/docs/white-labeling-authentication). This is *not* the easy path. We'd recommend Composio's managed apps, which require no additional configuration. Only do this if you specifically want your own branding.
30 +- **Manual, pre-connected auth**: members connect their tools ahead of time using [manual connections](/docs/authentication/manually-authenticating), and the agent just uses whatever is there.
31 +- **White-labelling** (advanced): your own Slack app and bot identity, via [white-labelling](/docs/authentication/white-labeling-authentication). This is *not* the easy path. We'd recommend Composio's managed apps, which require no additional configuration. Only do this if you specifically want your own branding.
32 - **The proxy** (advanced): using [`proxyExecute`](/docs/extending-sessions/proxy-execute) to call Slack API endpoints Composio doesn't wrap as tools.
33
34 It is **not** an example of [in-chat or dynamic auth](/docs/authentication) (asking a user to connect a tool mid-run), and it's more setup than many bots need. If you'd rather have a Slack bot with zero setup (Composio's managed app) or in-chat auth, start with the [general Slack bot](/examples/general-agent-with-pi) instead.
@@ -61,7 +61,7 @@ This bot doesn't post as "Composio". It posts as *my* app, with its own name, ic
61
62 <Figure src="/images/standup-slackbot/bot-avatar.png" alt="The Daily Standup Bot avatar" size="sm" />
63
64 -That's [white-labelling](/docs/white-labeling-authentication): you bring your own Slack app's credentials instead of using Composio-managed ones. Composio-managed auth needs no setup at all; white-labelling is the trade-off, you register and configure your own Slack app first. It's more work, but the bot is fully yours.
64 +That's [white-labelling](/docs/authentication/white-labeling-authentication): you bring your own Slack app's credentials instead of using Composio-managed ones. Composio-managed auth needs no setup at all; white-labelling is the trade-off, you register and configure your own Slack app first. It's more work, but the bot is fully yours.
65
66 Slack's app-creation UI changes from time to time, so the exact screens below may differ. First, the Slack app itself.
67
@@ -87,7 +87,7 @@ Slack's app-creation UI changes from time to time, so the exact screens below ma
87
88 ## Auth the bot
89
90 -The Slack app exists; now connect it through Composio so your code can act as it. You create one `slackbot` auth config from your credentials, then a setup script does the OAuth once with Composio's [manual authentication](/docs/manually-authenticating) flow.
90 +The Slack app exists; now connect it through Composio so your code can act as it. You create one `slackbot` auth config from your credentials, then a setup script does the OAuth once with Composio's [manual authentication](/docs/authentication/manually-authenticating) flow.
91
92 <Callout type="info" title="`slackbot` vs `slack`" className="[&_ul]:my-2 [&_ul]:list-disc [&_ul]:pl-5 [&_li]:my-1 [&_li]:pl-1">
93
@@ -224,7 +224,7 @@ The bot posts the result back as a draft the member can confirm or edit:
224 Edit `standup.config.ts` with your team (each member's Slack email and timezone, plus your channel and GitHub org), set your four environment variables, run `npx tsx scripts/setup.ts` once to connect your bot, then `vercel deploy`.
225 <Cards>
226 <Card title="Configuring sessions" href="/docs/configuring-sessions" description="What a session can scope: toolkits, tools, connections, and connection management" />
227 - <Card title="White-labeling authentication" href="/docs/white-labeling-authentication" description="Ship a bot under your own app's name, icon, and credentials" />
228 - <Card title="Custom vs managed auth" href="/docs/custom-app-vs-managed-app" description="Bring-your-own Slack app versus a Composio-managed connection" />
227 + <Card title="White-labeling authentication" href="/docs/authentication/white-labeling-authentication" description="Ship a bot under your own app's name, icon, and credentials" />
228 + <Card title="Custom vs managed auth" href="/docs/authentication/custom-app-vs-managed-app" description="Bring-your-own Slack app versus a Composio-managed connection" />
229 <Card title="Triggers" href="/docs/triggers" description="Run agents in response to events: schedules, webhooks, and app activity" />
230 </Cards>
docs/content/reference/api-reference/auth-configs/index.mdx
+2 -2
@@ -15,7 +15,7 @@ Each auth config defines:
15 - **Scopes**: what your tools are allowed to do on the user's behalf
16 - **Credentials**: Composio's managed app, or your own OAuth client and secrets
17
18 -Reach for a custom auth config when you need your own branding on consent screens, custom scopes, a dedicated rate-limit quota, or a custom toolkit instance. See [managed vs custom auth](/docs/custom-app-vs-managed-app) for the decision and [how Composio handles authentication](/docs/authentication) for the full picture.
18 +Reach for a custom auth config when you need your own branding on consent screens, custom scopes, a dedicated rate-limit quota, or a custom toolkit instance. See [managed vs custom auth](/docs/authentication/custom-app-vs-managed-app) for the decision and [how Composio handles authentication](/docs/authentication) for the full picture.
19
20 ## Auth schemes
21
@@ -28,7 +28,7 @@ The `auth_scheme` on an auth config determines how users authenticate to the too
28 | `BEARER_TOKEN` | A bearer access token you already hold (for example, from your own OAuth flow). Composio sends it as `Authorization: Bearer <token>` and does not refresh it, so you keep it current. | Bringing an existing OAuth or server-to-server token into Composio, or apps that issue long-lived tokens. |
29 | `BASIC` | HTTP Basic authentication with a username and password. | Services that use Basic Auth. |
30
31 -Most OAuth toolkits work out of the box with Composio managed auth. For the others you supply the credential fields. To choose or customize the scheme, see [managed vs custom auth](/docs/custom-app-vs-managed-app).
31 +Most OAuth toolkits work out of the box with Composio managed auth. For the others you supply the credential fields. To choose or customize the scheme, see [managed vs custom auth](/docs/authentication/custom-app-vs-managed-app).
32
33 These endpoints use your project API key in the `x-api-key` header. Each auth config is addressed by its `nanoid`, and you can enable or disable one without deleting it.
34
docs/content/reference/api-reference/connected-accounts/index.mdx
+2 -2
@@ -9,7 +9,7 @@ A connected account is a single user's authorized connection to a toolkit. It st
9
10 Composio creates a connected account when a user completes the flow defined by an [auth config](/reference/api-reference/auth-configs). From there you manage its full lifecycle:
11
12 -- **Create or link**: start a new connection, or generate an auth link session for the user to authorize. See [manually authenticating users](/docs/manually-authenticating).
12 +- **Create or link**: start a new connection, or generate an auth link session for the user to authorize. See [manually authenticating users](/docs/authentication/manually-authenticating).
13 - **Refresh**: renew authentication for an account whose tokens have expired.
14 - **Enable, disable, or update**: change an account's status or metadata without removing it.
15 - **Revoke or delete**: revoke the grant at the provider, or remove the account from Composio.
@@ -20,7 +20,7 @@ Each account is addressed by its `nanoid`. List endpoints accept filters so you
20
21 A Composio Connect Link is a hosted, secure sign-in page. You create one with the create auth link session endpoint, redirect the user to the returned URL, and Composio handles the rest: the user signs in, Composio creates the connected account, and Composio stores and refreshes its tokens. Credentials never pass through your app. This works for all Composio managed connections, with no OAuth credentials to set up.
22
23 -By default a connected account is `PRIVATE` and usable only by its owning user. Mark one `SHARED` to let other users reach it through a per-connection access control list. See [shared connections](/docs/shared-connections).
23 +By default a connected account is `PRIVATE` and usable only by its owning user. Mark one `SHARED` to let other users reach it through a per-connection access control list. See [shared connections](/docs/extending-sessions/shared-connections).
24
25 These endpoints use your project API key in the `x-api-key` header.
26
docs/content/reference/glossary.mdx
+3 -3
@@ -32,7 +32,7 @@ A hosted page where a user authorizes access to a toolkit. It is returned as a `
32 </GlossaryTerm>
33
34 <GlossaryTerm name="Connected Account">
35 -A stored set of credentials (OAuth tokens or API keys) linked to a userID, created when a user authenticates with a toolkit. Composio refreshes OAuth tokens automatically, and a user can have [multiple connected accounts](/docs/managing-multiple-connected-accounts) for the same toolkit. IDs are prefixed `ca_`.
35 +A stored set of credentials (OAuth tokens or API keys) linked to a userID, created when a user authenticates with a toolkit. Composio refreshes OAuth tokens automatically, and a user can have [multiple connected accounts](/docs/authentication/managing-multiple-connected-accounts) for the same toolkit. IDs are prefixed `ca_`.
36 </GlossaryTerm>
37
38 <GlossaryTerm name="Connection Request">
@@ -52,7 +52,7 @@ An open protocol for connecting AI models to external tools. Create a session wi
52 </GlossaryTerm>
53
54 <GlossaryTerm name="Manual Authentication">
55 -Authenticating users from your own code with `session.authorize()` or `connectedAccounts.link()`, rather than letting the agent handle it through in-chat authentication. See [Manual authentication](/docs/manually-authenticating).
55 +Authenticating users from your own code with `session.authorize()` or `connectedAccounts.link()`, rather than letting the agent handle it through in-chat authentication. See [Manual authentication](/docs/authentication/manually-authenticating).
56 </GlossaryTerm>
57
58 <GlossaryTerm name="Meta Tools">
@@ -136,7 +136,7 @@ An identifier from your application that Composio uses to scope connected accoun
136 </GlossaryTerm>
137
138 <GlossaryTerm name="White-Labeling">
139 -Customizing the auth experience so users see your brand during the OAuth flow. You provide your own OAuth credentials, redirect URIs, and branding. See [White-labeling authentication](/docs/white-labeling-authentication).
139 +Customizing the auth experience so users see your brand during the OAuth flow. You provide your own OAuth credentials, redirect URIs, and branding. See [White-labeling authentication](/docs/authentication/white-labeling-authentication).
140 </GlossaryTerm>
141
142 <GlossaryTerm name="Sandbox">
docs/content/reference/v3/api-reference/auth-configs/index.mdx
+2 -2
@@ -15,7 +15,7 @@ Each auth config defines:
15 - **Scopes**: what your tools are allowed to do on the user's behalf
16 - **Credentials**: Composio's managed app, or your own OAuth client and secrets
17
18 -Reach for a custom auth config when you need your own branding on consent screens, custom scopes, a dedicated rate-limit quota, or a custom toolkit instance. See [managed vs custom auth](/docs/custom-app-vs-managed-app) for the decision and [how Composio handles authentication](/docs/authentication) for the full picture.
18 +Reach for a custom auth config when you need your own branding on consent screens, custom scopes, a dedicated rate-limit quota, or a custom toolkit instance. See [managed vs custom auth](/docs/authentication/custom-app-vs-managed-app) for the decision and [how Composio handles authentication](/docs/authentication) for the full picture.
19
20 ## Auth schemes
21
@@ -28,7 +28,7 @@ The `auth_scheme` on an auth config determines how users authenticate to the too
28 | `BEARER_TOKEN` | A bearer access token you already hold (for example, from your own OAuth flow). Composio sends it as `Authorization: Bearer <token>` and does not refresh it, so you keep it current. | Bringing an existing OAuth or server-to-server token into Composio, or apps that issue long-lived tokens. |
29 | `BASIC` | HTTP Basic authentication with a username and password. | Services that use Basic Auth. |
30
31 -Most OAuth toolkits work out of the box with Composio managed auth. For the others you supply the credential fields. To choose or customize the scheme, see [managed vs custom auth](/docs/custom-app-vs-managed-app).
31 +Most OAuth toolkits work out of the box with Composio managed auth. For the others you supply the credential fields. To choose or customize the scheme, see [managed vs custom auth](/docs/authentication/custom-app-vs-managed-app).
32
33 These endpoints use your project API key in the `x-api-key` header. Each auth config is addressed by its `nanoid`, and you can enable or disable one without deleting it.
34
docs/content/reference/v3/api-reference/connected-accounts/index.mdx
+2 -2
@@ -9,7 +9,7 @@ A connected account is a single user's authorized connection to a toolkit. It st
9
10 Composio creates a connected account when a user completes the flow defined by an [auth config](/reference/api-reference/auth-configs). From there you manage its full lifecycle:
11
12 -- **Create or link**: start a new connection, or generate an auth link session for the user to authorize. See [manually authenticating users](/docs/manually-authenticating).
12 +- **Create or link**: start a new connection, or generate an auth link session for the user to authorize. See [manually authenticating users](/docs/authentication/manually-authenticating).
13 - **Refresh**: renew authentication for an account whose tokens have expired.
14 - **Enable, disable, or update**: change an account's status or metadata without removing it.
15 - **Revoke or delete**: revoke the grant at the provider, or remove the account from Composio.
@@ -20,7 +20,7 @@ Each account is addressed by its `nanoid`. List endpoints accept filters so you
20
21 A Composio Connect Link is a hosted, secure sign-in page. You create one with the create auth link session endpoint, redirect the user to the returned URL, and Composio handles the rest: the user signs in, Composio creates the connected account, and Composio stores and refreshes its tokens. Credentials never pass through your app. This works for all Composio managed connections, with no OAuth credentials to set up.
22
23 -By default a connected account is `PRIVATE` and usable only by its owning user. Mark one `SHARED` to let other users reach it through a per-connection access control list. See [shared connections](/docs/shared-connections).
23 +By default a connected account is `PRIVATE` and usable only by its owning user. Mark one `SHARED` to let other users reach it through a per-connection access control list. See [shared connections](/docs/extending-sessions/shared-connections).
24
25 These endpoints use your project API key in the `x-api-key` header.
26
docs/content/toolkits/faq/gmail.md
+2 -2
@@ -14,11 +14,11 @@ When using custom OAuth credentials, the Gmail API must be enabled in the Google
14
15 ## Why am I getting "Error 400: invalid_scope"?
16
17 -The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/programmatic-auth-configs).
17 +The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/authentication/programmatic-auth-configs).
18
19 ## Why does the OAuth consent screen show "Composio" instead of my app?
20
21 -By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).
21 +By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/authentication/white-labeling-authentication#using-your-own-oauth-apps).
22
23 ## Why am I getting 401 errors on tool calls?
24
docs/content/toolkits/faq/google_classroom.md
+2 -2
@@ -14,11 +14,11 @@ When using custom OAuth credentials, the Google Classroom API must be enabled in
14
15 ## Why am I getting "Error 400: invalid_scope"?
16
17 -The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/programmatic-auth-configs).
17 +The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/authentication/programmatic-auth-configs).
18
19 ## Why does the OAuth consent screen show "Composio" instead of my app?
20
21 -By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).
21 +By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/authentication/white-labeling-authentication#using-your-own-oauth-apps).
22
23 ## Why am I getting 401 errors on tool calls?
24
docs/content/toolkits/faq/google_maps.md
+2 -2
@@ -14,11 +14,11 @@ When using custom OAuth credentials, the Google Maps API must be enabled in the
14
15 ## Why am I getting "Error 400: invalid_scope"?
16
17 -The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/programmatic-auth-configs).
17 +The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/authentication/programmatic-auth-configs).
18
19 ## Why does the OAuth consent screen show "Composio" instead of my app?
20
21 -By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).
21 +By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/authentication/white-labeling-authentication#using-your-own-oauth-apps).
22
23 ## Why am I getting 401 errors on tool calls?
24
docs/content/toolkits/faq/googlecalendar.md
+2 -2
@@ -14,11 +14,11 @@ When using custom OAuth credentials, the Google Calendar API must be enabled in
14
15 ## Why am I getting "Error 400: invalid_scope"?
16
17 -The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/programmatic-auth-configs).
17 +The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/authentication/programmatic-auth-configs).
18
19 ## Why does the OAuth consent screen show "Composio" instead of my app?
20
21 -By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).
21 +By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/authentication/white-labeling-authentication#using-your-own-oauth-apps).
22
23 ## Why am I getting 401 errors on tool calls?
24
docs/content/toolkits/faq/googledocs.md
+2 -2
@@ -14,11 +14,11 @@ When using custom OAuth credentials, the Google Docs API must be enabled in the
14
15 ## Why am I getting "Error 400: invalid_scope"?
16
17 -The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/programmatic-auth-configs).
17 +The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/authentication/programmatic-auth-configs).
18
19 ## Why does the OAuth consent screen show "Composio" instead of my app?
20
21 -By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).
21 +By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/authentication/white-labeling-authentication#using-your-own-oauth-apps).
22
23 ## Why am I getting 401 errors on tool calls?
24
docs/content/toolkits/faq/googledrive.md
+2 -2
@@ -14,11 +14,11 @@ When using custom OAuth credentials, the Google Drive API must be enabled in the
14
15 ## Why am I getting "Error 400: invalid_scope"?
16
17 -The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/programmatic-auth-configs).
17 +The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/authentication/programmatic-auth-configs).
18
19 ## Why does the OAuth consent screen show "Composio" instead of my app?
20
21 -By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).
21 +By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/authentication/white-labeling-authentication#using-your-own-oauth-apps).
22
23 ## Why am I getting 401 errors on tool calls?
24
docs/content/toolkits/faq/googlemeet.md
+2 -2
@@ -14,11 +14,11 @@ When using custom OAuth credentials, the Google Meet API must be enabled in the
14
15 ## Why am I getting "Error 400: invalid_scope"?
16
17 -The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/programmatic-auth-configs).
17 +The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/authentication/programmatic-auth-configs).
18
19 ## Why does the OAuth consent screen show "Composio" instead of my app?
20
21 -By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).
21 +By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/authentication/white-labeling-authentication#using-your-own-oauth-apps).
22
23 ## Why am I getting 401 errors on tool calls?
24
docs/content/toolkits/faq/googlesheets.md
+2 -2
@@ -14,11 +14,11 @@ When using custom OAuth credentials, the Google Sheets API must be enabled in th
14
15 ## Why am I getting "Error 400: invalid_scope"?
16
17 -The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/programmatic-auth-configs).
17 +The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/authentication/programmatic-auth-configs).
18
19 ## Why does the OAuth consent screen show "Composio" instead of my app?
20
21 -By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).
21 +By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/authentication/white-labeling-authentication#using-your-own-oauth-apps).
22
23 ## Why am I getting 401 errors on tool calls?
24
docs/content/toolkits/faq/googleslides.md
+2 -2
@@ -14,11 +14,11 @@ When using custom OAuth credentials, the Google Slides API must be enabled in th
14
15 ## Why am I getting "Error 400: invalid_scope"?
16
17 -The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/programmatic-auth-configs).
17 +The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/authentication/programmatic-auth-configs).
18
19 ## Why does the OAuth consent screen show "Composio" instead of my app?
20
21 -By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).
21 +By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/authentication/white-labeling-authentication#using-your-own-oauth-apps).
22
23 ## Why am I getting 401 errors on tool calls?
24
docs/content/toolkits/faq/googlesuper.md
+2 -2
@@ -14,8 +14,8 @@ When using custom OAuth credentials, the required Google API must be enabled in
14
15 ## Why am I getting "Error 400: invalid_scope"?
16
17 -The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/programmatic-auth-configs).
17 +The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/authentication/programmatic-auth-configs).
18
19 ## Why does the OAuth consent screen show "Composio" instead of my app?
20
21 -By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).
21 +By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/authentication/white-labeling-authentication#using-your-own-oauth-apps).
docs/content/toolkits/faq/googletasks.md
+2 -2
@@ -14,11 +14,11 @@ When using custom OAuth credentials, the Google Tasks API must be enabled in the
14
15 ## Why am I getting "Error 400: invalid_scope"?
16
17 -The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/programmatic-auth-configs).
17 +The requested scopes are invalid or incorrectly formatted in the authorization URL. Verify your scope values against the [Google OAuth scopes docs](https://developers.google.com/identity/protocols/oauth2). If you're creating auth configs programmatically, see the [programmatic auth config guide](/docs/authentication/programmatic-auth-configs).
18
19 ## Why does the OAuth consent screen show "Composio" instead of my app?
20
21 -By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).
21 +By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/authentication/white-labeling-authentication#using-your-own-oauth-apps).
22
23 ## Why am I getting 401 errors on tool calls?
24
docs/content/toolkits/managed-auth.mdx
+1 -1
@@ -41,7 +41,7 @@ You need a custom auth config when you want to:
41 - **Request specific scopes** beyond Composio's defaults.
42 - **Use a toolkit without managed auth**, where you supply an API key, bearer token, or instance details.
43
44 -See [Managed vs custom auth](/docs/custom-app-vs-managed-app) for the full decision guide and setup steps. You can mix the two: use your own credentials for some toolkits and managed auth for the rest.
44 +See [Managed vs custom auth](/docs/authentication/custom-app-vs-managed-app) for the full decision guide and setup steps. You can mix the two: use your own credentials for some toolkits and managed auth for the rest.
45
46 ## Find a toolkit
47
docs/lib/standup-bot-source.json
+1 -1
@@ -46,7 +46,7 @@
46 },
47 {
48 "path": "scripts/setup.ts",
49 - "contents": "import { Composio } from \"@composio/core\";\nimport { env } from \"../api/_utils/env\";\n\n// One-time setup: connect the bot's Slack (\"slackbot\") account so it can post to\n// the channel and DM members. Run with `npx tsx scripts/setup.ts`, or\n// `--reconnect` to clear and re-do the OAuth (needed after changing Slack scopes).\nconst COMPOSIO_BASE_URL = \"https://backend.composio.dev\";\nconst TOOLKIT_SLUG = \"slackbot\";\n\n// Scopes the bot's OAuth *user* token must carry. Composio freezes the scopes at\n// connect time, so we check them before connecting and tell the user what to add.\nconst REQUIRED_USER_SCOPES = [\"team:read\"];\n\nconst log = {\n ok: (msg: string) => console.log(` ✅ ${msg}`),\n info: (msg: string) => console.log(` · ${msg}`),\n warn: (msg: string) => console.log(` ⚠️ ${msg}`),\n};\n\nfunction errMessage(err: unknown): string {\n if (err && typeof err === \"object\") {\n const e = err as {\n error?: { error?: { message?: string }; message?: string };\n message?: string;\n };\n return e.error?.error?.message ?? e.error?.message ?? e.message ?? String(err);\n }\n return String(err);\n}\n\nasync function main() {\n const RECONNECT = process.argv.includes(\"--reconnect\");\n\n console.log(\"\\n╭─────────────────────────────────────────────────────────╮\");\n console.log(\"│ Daily Standup Bot: One-Time Setup │\");\n console.log(\"╰─────────────────────────────────────────────────────────╯\");\n if (RECONNECT) {\n console.log(\" (--reconnect: will clear and re-do the bot's Slack auth)\");\n }\n\n const composio = new Composio({ apiKey: env.COMPOSIO_API_KEY });\n const authConfigId = env.COMPOSIO_SLACKBOT_AUTH_CONFIG_ID;\n\n // Check the auth config requests the scopes the bot needs.\n // READ-ONLY on purpose. GET returns secrets MASKED, and a PATCH that echoes\n // those masked values back overwrites the real client_secret with the mask.\n // So we never write credentials here; we only check and warn.\n const cfgRes = await fetch(`${COMPOSIO_BASE_URL}/api/v3/auth_configs/${authConfigId}`, {\n headers: { \"x-api-key\": env.COMPOSIO_API_KEY },\n });\n if (cfgRes.ok) {\n const cfg = (await cfgRes.json().catch(() => ({}))) as {\n credentials?: { user_scopes?: string[] };\n };\n const userScopes = cfg.credentials?.user_scopes ?? [];\n const missing = REQUIRED_USER_SCOPES.filter((s) => !userScopes.includes(s));\n if (missing.length > 0) {\n log.warn(`Auth config is missing required user scope(s): ${missing.join(\", \")}`);\n console.log(\n \" Add them under the auth config's User Token Scopes in the Composio\\n\" +\n \" dashboard (Auth Configs → slackbot), then re-run with --reconnect.\"\n );\n } else {\n log.ok(\"Auth config has the required user scopes.\");\n }\n }\n\n // Ensure the bot's Slack connection is active.\n const session = await composio.create(\"default\", {\n authConfigs: { slackbot: authConfigId },\n });\n\n async function listSlackbotAccounts() {\n try {\n const res = await composio.connectedAccounts.list({\n userIds: [\"default\"],\n toolkitSlugs: [TOOLKIT_SLUG],\n });\n return res.items;\n } catch {\n return [];\n }\n }\n\n if (RECONNECT) {\n const accounts = await listSlackbotAccounts();\n if (accounts.length === 0) {\n log.info(\"No existing connections to clear.\");\n } else {\n for (const acc of accounts) {\n try {\n await composio.connectedAccounts.delete(acc.id);\n log.ok(`Removed old connection ${acc.id}.`);\n } catch (err) {\n log.warn(`Could not remove ${acc.id}: ${errMessage(err)}`);\n }\n }\n }\n }\n\n let connected = false;\n if (!RECONNECT) {\n const toolkits = await session.toolkits({ toolkits: [TOOLKIT_SLUG] });\n connected = !!toolkits.items.find((t) => t.slug === TOOLKIT_SLUG)?.connection\n ?.isActive;\n }\n\n if (connected) {\n log.ok(\"Bot is already connected to Slack.\");\n } else {\n log.info(\"Bot is not connected yet. Generating an authorization link…\");\n // Manual authentication: authorize() returns a Connect Link, then\n // waitForConnection() resolves once the bot finishes OAuth in the browser.\n // https://docs.composio.dev/docs/manually-authenticating\n const connectionRequest = await session.authorize(TOOLKIT_SLUG);\n if (!connectionRequest.redirectUrl) {\n throw new Error(\"Composio did not return an authorization link.\");\n }\n\n console.log(\"\\n Open this URL in your browser to authorize the bot:\\n\");\n console.log(` ${connectionRequest.redirectUrl}\\n`);\n console.log(\" Waiting for you to complete the OAuth flow (Ctrl+C to abort)…\");\n\n const TIMEOUT_MS = 5 * 60 * 1000;\n const account = await connectionRequest.waitForConnection(TIMEOUT_MS);\n log.ok(`Bot connected to Slack (${account.id}).`);\n }\n\n console.log(`\\n${\"─\".repeat(70)}`);\n console.log(\" 🎉 Setup complete. Invite the bot to your standup channel and\");\n console.log(\" point your Slack app's Interactivity Request URL at\");\n console.log(\" https://<your-deployment>/api/interactivity\");\n console.log(`${\"─\".repeat(70)}\\n`);\n}\n\nmain().catch((err) => {\n console.error(`\\n ❌ ${errMessage(err)}\\n`);\n process.exit(1);\n});\n",
49 + "contents": "import { Composio } from \"@composio/core\";\nimport { env } from \"../api/_utils/env\";\n\n// One-time setup: connect the bot's Slack (\"slackbot\") account so it can post to\n// the channel and DM members. Run with `npx tsx scripts/setup.ts`, or\n// `--reconnect` to clear and re-do the OAuth (needed after changing Slack scopes).\nconst COMPOSIO_BASE_URL = \"https://backend.composio.dev\";\nconst TOOLKIT_SLUG = \"slackbot\";\n\n// Scopes the bot's OAuth *user* token must carry. Composio freezes the scopes at\n// connect time, so we check them before connecting and tell the user what to add.\nconst REQUIRED_USER_SCOPES = [\"team:read\"];\n\nconst log = {\n ok: (msg: string) => console.log(` ✅ ${msg}`),\n info: (msg: string) => console.log(` · ${msg}`),\n warn: (msg: string) => console.log(` ⚠️ ${msg}`),\n};\n\nfunction errMessage(err: unknown): string {\n if (err && typeof err === \"object\") {\n const e = err as {\n error?: { error?: { message?: string }; message?: string };\n message?: string;\n };\n return e.error?.error?.message ?? e.error?.message ?? e.message ?? String(err);\n }\n return String(err);\n}\n\nasync function main() {\n const RECONNECT = process.argv.includes(\"--reconnect\");\n\n console.log(\"\\n╭─────────────────────────────────────────────────────────╮\");\n console.log(\"│ Daily Standup Bot: One-Time Setup │\");\n console.log(\"╰─────────────────────────────────────────────────────────╯\");\n if (RECONNECT) {\n console.log(\" (--reconnect: will clear and re-do the bot's Slack auth)\");\n }\n\n const composio = new Composio({ apiKey: env.COMPOSIO_API_KEY });\n const authConfigId = env.COMPOSIO_SLACKBOT_AUTH_CONFIG_ID;\n\n // Check the auth config requests the scopes the bot needs.\n // READ-ONLY on purpose. GET returns secrets MASKED, and a PATCH that echoes\n // those masked values back overwrites the real client_secret with the mask.\n // So we never write credentials here; we only check and warn.\n const cfgRes = await fetch(`${COMPOSIO_BASE_URL}/api/v3/auth_configs/${authConfigId}`, {\n headers: { \"x-api-key\": env.COMPOSIO_API_KEY },\n });\n if (cfgRes.ok) {\n const cfg = (await cfgRes.json().catch(() => ({}))) as {\n credentials?: { user_scopes?: string[] };\n };\n const userScopes = cfg.credentials?.user_scopes ?? [];\n const missing = REQUIRED_USER_SCOPES.filter((s) => !userScopes.includes(s));\n if (missing.length > 0) {\n log.warn(`Auth config is missing required user scope(s): ${missing.join(\", \")}`);\n console.log(\n \" Add them under the auth config's User Token Scopes in the Composio\\n\" +\n \" dashboard (Auth Configs → slackbot), then re-run with --reconnect.\"\n );\n } else {\n log.ok(\"Auth config has the required user scopes.\");\n }\n }\n\n // Ensure the bot's Slack connection is active.\n const session = await composio.create(\"default\", {\n authConfigs: { slackbot: authConfigId },\n });\n\n async function listSlackbotAccounts() {\n try {\n const res = await composio.connectedAccounts.list({\n userIds: [\"default\"],\n toolkitSlugs: [TOOLKIT_SLUG],\n });\n return res.items;\n } catch {\n return [];\n }\n }\n\n if (RECONNECT) {\n const accounts = await listSlackbotAccounts();\n if (accounts.length === 0) {\n log.info(\"No existing connections to clear.\");\n } else {\n for (const acc of accounts) {\n try {\n await composio.connectedAccounts.delete(acc.id);\n log.ok(`Removed old connection ${acc.id}.`);\n } catch (err) {\n log.warn(`Could not remove ${acc.id}: ${errMessage(err)}`);\n }\n }\n }\n }\n\n let connected = false;\n if (!RECONNECT) {\n const toolkits = await session.toolkits({ toolkits: [TOOLKIT_SLUG] });\n connected = !!toolkits.items.find((t) => t.slug === TOOLKIT_SLUG)?.connection\n ?.isActive;\n }\n\n if (connected) {\n log.ok(\"Bot is already connected to Slack.\");\n } else {\n log.info(\"Bot is not connected yet. Generating an authorization link…\");\n // Manual authentication: authorize() returns a Connect Link, then\n // waitForConnection() resolves once the bot finishes OAuth in the browser.\n // https://docs.composio.dev/docs/authentication/manually-authenticating\n const connectionRequest = await session.authorize(TOOLKIT_SLUG);\n if (!connectionRequest.redirectUrl) {\n throw new Error(\"Composio did not return an authorization link.\");\n }\n\n console.log(\"\\n Open this URL in your browser to authorize the bot:\\n\");\n console.log(` ${connectionRequest.redirectUrl}\\n`);\n console.log(\" Waiting for you to complete the OAuth flow (Ctrl+C to abort)…\");\n\n const TIMEOUT_MS = 5 * 60 * 1000;\n const account = await connectionRequest.waitForConnection(TIMEOUT_MS);\n log.ok(`Bot connected to Slack (${account.id}).`);\n }\n\n console.log(`\\n${\"─\".repeat(70)}`);\n console.log(\" 🎉 Setup complete. Invite the bot to your standup channel and\");\n console.log(\" point your Slack app's Interactivity Request URL at\");\n console.log(\" https://<your-deployment>/api/interactivity\");\n console.log(`${\"─\".repeat(70)}\\n`);\n}\n\nmain().catch((err) => {\n console.error(`\\n ❌ ${errMessage(err)}\\n`);\n process.exit(1);\n});\n",
50 "composio": true
51 }
52 ]
docs/next.config.mjs
+56 -14
@@ -298,27 +298,27 @@ const config = {
298 },
299 {
300 source: '/tool-router/manually-authenticating-users',
301 - destination: '/docs/manually-authenticating',
301 + destination: '/docs/authentication/manually-authenticating',
302 permanent: true,
303 },
304 {
305 source: '/tool-router/using-custom-auth-configs',
306 - destination: '/docs/custom-app-vs-managed-app',
306 + destination: '/docs/authentication/custom-app-vs-managed-app',
307 permanent: true,
308 },
309 {
310 source: '/docs/authenticating-users/using-custom-auth-configs',
311 - destination: '/docs/custom-app-vs-managed-app',
311 + destination: '/docs/authentication/custom-app-vs-managed-app',
312 permanent: true,
313 },
314 {
315 source: '/tool-router/white-labeling-authentication',
316 - destination: '/docs/white-labeling-authentication',
316 + destination: '/docs/authentication/white-labeling-authentication',
317 permanent: true,
318 },
319 {
320 source: '/tool-router/managing-multiple-accounts',
321 - destination: '/docs/managing-multiple-connected-accounts',
321 + destination: '/docs/authentication/managing-multiple-connected-accounts',
322 permanent: true,
323 },
324 // Provider redirects (old fern URLs -> new docs URLs)
@@ -439,23 +439,65 @@ const config = {
439 // Programmatic auth configs consolidated into the Customizing auth section
440 {
441 source: '/docs/auth-configuration/programmatic-auth-configs',
442 - destination: '/docs/programmatic-auth-configs',
442 + destination: '/docs/authentication/programmatic-auth-configs',
443 permanent: true,
444 },
445 // Authenticating users folder flattened into the Authenticate users section
446 {
447 source: '/docs/authenticating-users/manually-authenticating',
448 - destination: '/docs/manually-authenticating',
448 + destination: '/docs/authentication/manually-authenticating',
449 permanent: true,
450 },
451 {
452 source: '/docs/authenticating-users/managing-multiple-connected-accounts',
453 - destination: '/docs/managing-multiple-connected-accounts',
453 + destination: '/docs/authentication/managing-multiple-connected-accounts',
454 permanent: true,
455 },
456 {
457 source: '/docs/authenticating-users/shared-connections',
458 - destination: '/docs/shared-connections',
458 + destination: '/docs/extending-sessions/shared-connections',
459 + permanent: true,
460 + },
461 + // Auth guides regrouped under the Authentication folder; shared connections
462 + // moved to Extend sessions. These sources carry 36-42% Google entry traffic.
463 + {
464 + source: '/docs/manually-authenticating',
465 + destination: '/docs/authentication/manually-authenticating',
466 + permanent: true,
467 + },
468 + {
469 + source: '/docs/managing-multiple-connected-accounts',
470 + destination: '/docs/authentication/managing-multiple-connected-accounts',
471 + permanent: true,
472 + },
473 + {
474 + source: '/docs/importing-existing-connections',
475 + destination: '/docs/authentication/importing-existing-connections',
476 + permanent: true,
477 + },
478 + {
479 + source: '/docs/custom-app-vs-managed-app',
480 + destination: '/docs/authentication/custom-app-vs-managed-app',
481 + permanent: true,
482 + },
483 + {
484 + source: '/docs/programmatic-auth-configs',
485 + destination: '/docs/authentication/programmatic-auth-configs',
486 + permanent: true,
487 + },
488 + {
489 + source: '/docs/controlling-scopes',
490 + destination: '/docs/authentication/controlling-scopes',
491 + permanent: true,
492 + },
493 + {
494 + source: '/docs/white-labeling-authentication',
495 + destination: '/docs/authentication/white-labeling-authentication',
496 + permanent: true,
497 + },
498 + {
499 + source: '/docs/shared-connections',
500 + destination: '/docs/extending-sessions/shared-connections',
501 permanent: true,
502 },
503 // Authentication reference renamed to "Authenticating to Composio"
@@ -948,22 +990,22 @@ const config = {
990 },
991 {
992 source: '/docs/guides/managing-multiple-connected-accounts',
951 - destination: '/docs/managing-multiple-connected-accounts',
993 + destination: '/docs/authentication/managing-multiple-connected-accounts',
994 permanent: true,
995 },
996 {
997 source: '/docs/guides/white-labeling-authentication',
956 - destination: '/docs/white-labeling-authentication',
998 + destination: '/docs/authentication/white-labeling-authentication',
999 permanent: true,
1000 },
1001 {
1002 source: '/docs/using-custom-auth-configuration',
961 - destination: '/docs/custom-app-vs-managed-app',
1003 + destination: '/docs/authentication/custom-app-vs-managed-app',
1004 permanent: true,
1005 },
1006 {
1007 source: '/docs/guides/using-custom-auth-configuration',
966 - destination: '/docs/custom-app-vs-managed-app',
1008 + destination: '/docs/authentication/custom-app-vs-managed-app',
1009 permanent: true,
1010 },
1011 {
@@ -1047,7 +1089,7 @@ const config = {
1089 // Legacy /docs/white-labeling → sessions white-labeling page
1090 {
1091 source: '/docs/white-labeling',
1050 - destination: '/docs/white-labeling-authentication',
1092 + destination: '/docs/authentication/white-labeling-authentication',
1093 permanent: true,
1094 },
1095 ];
docs/tests/integration/redirects.test.ts
+3
@@ -37,6 +37,9 @@ const REDIRECTS = [
37 { from: "/docs/sandbox", to: "/docs/sandbox/remote" },
38 { from: "/docs/custom-tools-and-toolkits", to: "/docs/extending-sessions/custom-tools-and-toolkits" },
39 { from: "/docs/proxy-execute", to: "/docs/extending-sessions/proxy-execute" },
40 + { from: "/docs/white-labeling-authentication", to: "/docs/authentication/white-labeling-authentication" },
41 + { from: "/docs/shared-connections", to: "/docs/extending-sessions/shared-connections" },
42 + { from: "/docs/manually-authenticating", to: "/docs/authentication/manually-authenticating" },
43 ];
44
45 describe("Redirects - key patterns", () => {
docs/tests/static/navigation.test.ts
+3 -2
@@ -53,7 +53,8 @@ describe("Navigation - meta.json validity", () => {
53 "---Core concepts---",
54 "---Guides---",
55 "---Direct execution (legacy)---",
56 - "---Migration and security---",
56 + "---Migration---",
57 + "---Security and data---",
58 ]);
59
60 expect(pages.slice(1, pages.indexOf("---Core concepts---"))).toEqual([
@@ -68,7 +69,7 @@ describe("Navigation - meta.json validity", () => {
69 expect(
70 pages.slice(
71 pages.indexOf("---Direct execution (legacy)---") + 1,
71 - pages.indexOf("---Migration and security---")
72 + pages.indexOf("---Migration---")
73 )
74 ).toEqual([
75 "sessions-vs-direct-execution",
docs/tests/static/start-routing.test.ts
+14 -9
@@ -32,25 +32,30 @@ describe('getting-started routing policy', () => {
32 ]);
33 });
34
35 - test('keeps progressive authentication guides in the human and agent indexes', async () => {
36 - const [authentication, llmsRoute] = await Promise.all([
37 - read('content/docs/authentication.mdx'),
38 - read('app/llms.txt/route.ts'),
35 + test('keeps progressive authentication guides in the human hub and the sidebar', async () => {
36 + const [authentication, authMeta, sessionsMeta] = await Promise.all([
37 + read('content/docs/authentication/index.mdx'),
38 + read('content/docs/authentication/meta.json'),
39 + read('content/docs/extending-sessions/meta.json'),
40 ]);
40 - const guides = [
41 + const authGuides = [
42 'manually-authenticating',
43 'managing-multiple-connected-accounts',
43 - 'shared-connections',
44 'importing-existing-connections',
45 'custom-app-vs-managed-app',
46 'programmatic-auth-configs',
47 'controlling-scopes',
48 'white-labeling-authentication',
49 ];
50 + const authPages = JSON.parse(authMeta).pages as string[];
51 + const sessionPages = JSON.parse(sessionsMeta).pages as string[];
52
51 - for (const guide of guides) {
52 - expect(authentication).toContain(`href="/docs/${guide}"`);
53 - expect(llmsRoute).toContain(`'/docs/${guide}'`);
53 + for (const guide of authGuides) {
54 + expect(authentication).toContain(`href="/docs/authentication/${guide}"`);
55 + expect(authPages).toContain(guide);
56 }
57 +
58 + expect(authentication).toContain('href="/docs/extending-sessions/shared-connections"');
59 + expect(sessionPages).toContain('shared-connections');
60 });
61 });