@devries-cameron20 / composio-1 / commits / d497fe0cc
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: add auth config switching FAQ and troubleshooting links

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmitha Mallesh committed Mar 4, 2026 at 20:37 UTC d497fe0cc0e522abb12dccc8b4d89b9fcb01aee4
3 files changed +21
docs/content/docs/common-faq.mdx
+12
@@ -207,6 +207,18 @@ Create a new session when the config changes: different toolkits, different auth
207 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).
208 </Accordion>
209
210 +<Accordion title="What happens to existing connections when I switch to my own OAuth app?">
211 +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.
212 +
213 +- **Existing connections keep working.** Tokens continue refreshing using the original auth config's credentials.
214 +- **New connections use your custom auth config.** Users who connect after the switch see your app name on the consent screen.
215 +- **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.
216 +
217 +This applies whether you're using sessions or direct tool execution:
218 +- **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).
219 +- **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).
220 +</Accordion>
221 +
222 <Accordion title="How do I check complete logs / API calls from the SDK?">
223 Enable debug logging to view all API calls and network requests made by the SDK.
224
docs/content/docs/troubleshooting/authentication.mdx
+7
@@ -20,6 +20,13 @@ Ensure your OAuth app is configured correctly:
20
21 For setup guides by toolkit: [OAuth Configuration Guides](https://composio.dev/oauth)
22
23 +## Switching to a custom OAuth app
24 +
25 +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.
26 +
27 +- **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).
28 +- **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).
29 +
30 ## Common authentication issues
31
32 - **Invalid redirect URI**: Check the callback URL matches exactly
docs/content/docs/white-labeling-authentication.mdx
+2
@@ -155,7 +155,9 @@ const session = await composio.create("user_123", {
155 </Tab>
156 </Tabs>
157
158 +<Callout type="warn">
159 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.
160 +</Callout>
161
162 **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.
163