Skip to content

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

docs: remove inline FAQ, add cURL for managed auth check, cross-reference guides

Sushmitha Mallesh69e7866bbaad
diff --git a/docs/content/docs/common-faq.mdx b/docs/content/docs/common-faq.mdx
index a724046db..2c9556b8e 100644
--- a/docs/content/docs/common-faq.mdx
+++ b/docs/content/docs/common-faq.mdx
@@ -99,7 +99,7 @@ An auth config is a blueprint that defines how authentication works for a toolki
If you're using sessions with meta tools (`composio.create()`), you don't need to create auth configs yourself. When a user connects to a toolkit, Composio automatically uses a default auth config with managed credentials. The agent handles the entire flow through `COMPOSIO_MANAGE_CONNECTIONS`.
-You only need to create auth configs manually when you're [executing tools directly](/docs/tools-direct/authenticating-tools), want to [use your own OAuth app](/docs/white-labeling-authentication), need [custom scopes](/docs/auth-configuration/custom-auth-configs), or are working with a toolkit that doesn't have Composio-managed auth. See [Authentication](/docs/authentication) for the full overview.
+You only need to create auth configs manually when you're [executing tools directly](/docs/tools-direct/authenticating-tools), want to [use your own OAuth app](/docs/white-labeling-authentication), need [custom scopes](/docs/auth-configuration/custom-auth-configs), or are working with a toolkit that doesn't have Composio-managed auth. See [Authentication](/docs/authentication) for the full overview and [When to use your own developer credentials](/docs/custom-app-vs-managed-app) for help deciding.
</Accordion>
<Accordion title="What authentication types does Composio support?">
@@ -219,6 +219,21 @@ Create a new session when the config changes: different toolkits, different auth
Some toolkits require your own OAuth credentials or API keys. Create an auth config in the dashboard by selecting the toolkit, choosing the auth scheme, and entering your credentials. Then pass the auth config ID when creating a session using the `auth_configs` (or `auth_config_id`) parameter so the session uses your developer credentials instead of Composio-managed auth. See [Using custom auth configuration](/docs/using-custom-auth-configuration).
</Accordion>
+<Accordion title="When should I use my own developer credentials instead of Composio managed auth?">
+Use your own credentials when you're going to production and users will see OAuth consent screens, when you need custom scopes, when you're hitting shared rate limits, or when connecting to a self-hosted instance. For development and prototyping, Composio managed auth works out of the box with no setup. See [When to use your own developer credentials](/docs/custom-app-vs-managed-app).
+</Accordion>
+
+<Accordion title="How do I check if a toolkit has Composio managed auth?">
+Call the toolkits API and check the `composio_managed_auth_schemes` field:
+
+```bash
+curl 'https://backend.composio.dev/api/v3/toolkits/github' \
+ -H 'x-api-key: YOUR_API_KEY'
+```
+
+If the array is empty, you'll need to provide your own credentials. You can also check on each toolkit's page on the [toolkits page](/toolkits).
+</Accordion>
+
<Accordion title="What happens to existing connections when I switch to my own OAuth app?">
Nothing — existing connected accounts are permanently tied to the auth config they were created with. Switching to a custom auth config only affects new connections.
diff --git a/docs/content/docs/custom-app-vs-managed-app.mdx b/docs/content/docs/custom-app-vs-managed-app.mdx
index c9a09e76a..edab13c64 100644
--- a/docs/content/docs/custom-app-vs-managed-app.mdx
+++ b/docs/content/docs/custom-app-vs-managed-app.mdx
@@ -4,7 +4,7 @@ description: When to use your own OAuth credentials instead of Composio managed
keywords: [custom auth config, managed auth, oauth, auth config, white label, own developer credentials, decision]
---
-Composio supports two ways to authenticate users with toolkits. You can use them together, and most production apps do.
+Composio supports two ways to authenticate users with toolkits.
- **Composio managed apps**: Composio registers and maintains OAuth apps for popular toolkits (GitHub, Gmail, Slack, etc.). Zero setup, works out of the box.
- **Your own OAuth apps**: You register an OAuth app in the toolkit's developer portal and tell Composio to use your credentials instead.
@@ -15,28 +15,7 @@ Managed apps are the default. Every toolkit that supports OAuth has a Composio m
- **You're building and iterating.** No OAuth app registration, no credentials to manage. Create a session and start testing immediately.
- **Default scopes cover your needs.** Composio requests sensible defaults for each toolkit.
-- **Branding on consent screens doesn't matter.** Users will see "Composio wants to access your account" during OAuth. Fine for internal tools, prototypes, and development.
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
-<Tab value="Python">
-```python
-from composio import Composio
-
-composio = Composio()
-session = composio.create(user_id="user_123")
-# GitHub, Gmail, Slack, etc. all use Composio managed auth by default
-```
-</Tab>
-<Tab value="TypeScript">
-```typescript
-import { Composio } from '@composio/core';
-
-const composio = new Composio();
-const session = await composio.create("user_123");
-// GitHub, Gmail, Slack, etc. all use Composio managed auth by default
-```
-</Tab>
-</Tabs>
+- **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.
## When to use your own OAuth app
@@ -52,13 +31,15 @@ Bring your own credentials when any of these apply:
<Step>
<StepTitle>Register an OAuth app with the toolkit</StepTitle>
-Go to the toolkit's developer portal (e.g., [GitHub](https://github.com/settings/developers), [Google Cloud Console](https://console.cloud.google.com/)) and create a new OAuth app. Set the callback URL to:
+Go to the toolkit's developer portal and register a new OAuth app. You'll need to set the authorized redirect URI to:
```
https://backend.composio.dev/api/v3/toolkits/auth/callback
```
-Copy your **Client ID** and **Client Secret**.
+Once registered, copy your **Client ID** and **Client Secret**.
+
+Step-by-step guides for popular toolkits: [Google](https://composio.dev/auth/googleapps) | [GitHub](https://composio.dev/auth/github) | [Slack](https://composio.dev/auth/slack) | [HubSpot](https://composio.dev/auth/hubspot) | [All toolkits](https://composio.dev/auth)
</Step>
<Step>
@@ -111,9 +92,9 @@ const session = await composio.create("user_123", {
</Step>
</Steps>
-## Using both together
+## Mixing per toolkit
-Most production apps mix both. Use your own credentials for toolkits where users see consent screens (GitHub, Google, Slack) and let Composio managed auth handle the rest.
+You don't have to pick one approach for all toolkits. Use your own credentials for toolkits where users see consent screens (GitHub, Google, Slack) and Composio managed auth for the rest. Each toolkit gets its own auth config independently.
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
<Tab value="Python">
@@ -148,39 +129,18 @@ const session = await composio.create("user_123", {
Start with managed apps during development. When you're ready for production, register your own OAuth apps for the toolkits that matter and add the `auth_configs` parameter. No other code changes needed.
-Existing connected accounts keep working because they stay tied to the auth config they were created with. New connections go through your own credentials. See [Switching from managed to custom](/docs/white-labeling-authentication#switching-from-composio-managed-to-your-own-oauth-app) for details.
+If your users already have connections through Composio managed auth, you can import their existing tokens into your new auth config. See [Importing existing connections](/docs/importing-existing-connections).
### Toolkits without managed auth
-Some toolkits (PostHog, Tavily, Perplexity, etc.) don't have Composio managed auth. For these, you must create a custom auth config with your own credentials. See [Using custom auth configuration](/docs/using-custom-auth-configuration).
+Some toolkits don't have Composio managed auth. For these, you must create a custom auth config with your own credentials. You can check whether a toolkit has managed auth by calling the API:
-## FAQ
-
-<Accordions>
-<Accordion title="Can I use managed auth for some toolkits and custom apps for others?">
-Yes. Pass `auth_configs` only for the toolkits where you want your own credentials. Everything else automatically uses Composio managed auth. This is the most common pattern in production.
-</Accordion>
-
-<Accordion title="Will switching to a custom app break existing connected accounts?">
-No. Existing connected accounts are tied to the auth config they were created with and keep working. Only new connections go through your custom OAuth app. To fully migrate existing users, delete their old connected accounts and have them re-authenticate. See [Switching from managed to custom](/docs/white-labeling-authentication#switching-from-composio-managed-to-your-own-oauth-app).
-</Accordion>
-
-<Accordion title="Do I need a custom app for API key-based toolkits?">
-No. API key-based toolkits (like Tavily, Perplexity) don't have OAuth consent screens, so there's no branding to customize. You still need to create a custom auth config to provide your API key, but you don't need to register an OAuth app.
-</Accordion>
-
-<Accordion title="Does Composio still handle token refresh with custom apps?">
-Yes. Composio manages token refresh regardless of whether you use managed or custom OAuth credentials. You don't need to handle re-authentication or token expiration.
-</Accordion>
-
-<Accordion title="What happens if Composio's managed OAuth app hits rate limits?">
-Managed apps share quota across all Composio users. If you're seeing rate limit errors, switching to your own OAuth app gives you a dedicated quota. This is one of the main reasons to use your own app in production.
-</Accordion>
+```bash
+curl 'https://backend.composio.dev/api/v3/toolkits/posthog' \
+ -H 'x-api-key: YOUR_API_KEY'
+```
-<Accordion title="Can I create custom auth configs programmatically?">
-Yes. Use the SDK instead of the dashboard. See [Programmatic auth configs](/docs/auth-configuration/programmatic-auth-configs) for examples.
-</Accordion>
-</Accordions>
+If the `composio_managed_auth_schemes` array is empty, you'll need to provide your own credentials. You can also check on each toolkit's page on the [toolkits page](/toolkits). See [Using custom auth configuration](/docs/using-custom-auth-configuration) for a step-by-step walkthrough.
## What to read next
diff --git a/docs/content/docs/using-custom-auth-configuration.mdx b/docs/content/docs/using-custom-auth-configuration.mdx
index 56921ff2c..a693f641b 100644
--- a/docs/content/docs/using-custom-auth-configuration.mdx
+++ b/docs/content/docs/using-custom-auth-configuration.mdx
@@ -33,6 +33,8 @@ Copy the auth config ID (e.g., `ac_1234abcd`).
<Callout type="info">
For detailed instructions on getting credentials for specific toolkits, see [Custom auth configs](/docs/auth-configuration/custom-auth-configs).
+
+Step-by-step guides for popular toolkits: [Google](https://composio.dev/auth/googleapps) | [GitHub](https://composio.dev/auth/github) | [Slack](https://composio.dev/auth/slack) | [HubSpot](https://composio.dev/auth/hubspot) | [All toolkits](https://composio.dev/auth)
</Callout>
</Step>
@@ -73,6 +75,7 @@ Your session will now use this auth config when users connect to this toolkit.
## What to read next
<Cards>
+ <Card icon={<Key />} title="When to use your own developer credentials" href="/docs/custom-app-vs-managed-app" description="Decide when to use Composio managed auth and when to bring your own" />
<Card icon={<Palette />} title="White-labeling authentication" href="/docs/white-labeling-authentication" description="Use your own OAuth apps so users see your branding on consent screens" />
<Card icon={<Key />} title="Authentication overview" href="/docs/authentication" description="Connect Links, OAuth, API keys, and how Composio manages auth" />
<Card icon={<Wrench />} title="Configuring sessions" href="/docs/configuring-sessions" description="Pass auth configs, connected accounts, and toolkit restrictions to sessions" />