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: add auth config switching FAQ and troubleshooting links

Sushmitha Malleshd497fe0cc0e5
diff --git a/docs/content/docs/common-faq.mdx b/docs/content/docs/common-faq.mdx
index 3b897d5c4..d9ba3a22a 100644
--- a/docs/content/docs/common-faq.mdx
+++ b/docs/content/docs/common-faq.mdx
@@ -207,6 +207,18 @@ 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="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.
+
+- **Existing connections keep working.** Tokens continue refreshing using the original auth config's credentials.
+- **New connections use your custom auth config.** Users who connect after the switch see your app name on the consent screen.
+- **To fully migrate a user**, delete their old connected account and have them re-authenticate through your OAuth app. There is no way to move an existing connection between auth configs without re-authentication.
+
+This applies whether you're using sessions or direct tool execution:
+- **Sessions:** Pass `authConfigs` when calling `composio.create()`. See [Switching auth configs (sessions)](/docs/white-labeling-authentication#switching-from-composio-managed-to-your-own-oauth-app).
+- **Direct tool execution:** Pass the new `authConfigId` when calling `initiate()`. See [Switching auth configs (direct)](/docs/auth-configuration/white-labeling#switching-from-composio-managed-to-your-own-oauth-app).
+</Accordion>
+
<Accordion title="How do I check complete logs / API calls from the SDK?">
Enable debug logging to view all API calls and network requests made by the SDK.
diff --git a/docs/content/docs/troubleshooting/authentication.mdx b/docs/content/docs/troubleshooting/authentication.mdx
index 5ae5d647f..ca6b3c354 100644
--- a/docs/content/docs/troubleshooting/authentication.mdx
+++ b/docs/content/docs/troubleshooting/authentication.mdx
@@ -20,6 +20,13 @@ Ensure your OAuth app is configured correctly:
For setup guides by toolkit: [OAuth Configuration Guides](https://composio.dev/oauth)
+## Switching to a custom OAuth app
+
+If you're moving from Composio-managed auth to your own OAuth app, existing connections are not affected. New connections will use your custom auth config. To fully migrate users, delete their old connected accounts and have them re-authenticate.
+
+- **Sessions:** Pass `authConfigs` when calling `composio.create()`. See [Switching auth configs (sessions)](/docs/white-labeling-authentication#switching-from-composio-managed-to-your-own-oauth-app).
+- **Direct tool execution:** Pass the new `authConfigId` when calling `initiate()`. See [Switching auth configs (direct)](/docs/auth-configuration/white-labeling#switching-from-composio-managed-to-your-own-oauth-app).
+
## Common authentication issues
- **Invalid redirect URI**: Check the callback URL matches exactly
diff --git a/docs/content/docs/white-labeling-authentication.mdx b/docs/content/docs/white-labeling-authentication.mdx
index 2a7981a5a..b8327b395 100644
--- a/docs/content/docs/white-labeling-authentication.mdx
+++ b/docs/content/docs/white-labeling-authentication.mdx
@@ -155,7 +155,9 @@ const session = await composio.create("user_123", {
</Tab>
</Tabs>
+<Callout type="warn">
Existing users' connections continue using Composio's OAuth client credentials for token refresh until they re-authenticate. Composio does not see or store the user's data.
+</Callout>
**Fully migrate all users.** To move every user to your OAuth app, delete their old connected accounts and have them re-authenticate. There is no way to move an existing connection from one auth config to another without re-authentication.