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(scopes): sections for developer-side scope fixes (PLEN-4631)
Scope-failure responses link developers to Controlling scopes. The managed app case already has a section (own OAuth app); it now says when you need it. Add the auth-scheme case as a new section. The reconnect note for updated configs is already on the page. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sankaran committed
Nov 12, 2026 at 11:34 UTC
e3648d37a8e14376d7f1568183574637e00e23a7
1 file changed
+5
-1
docs/content/docs/authentication/controlling-scopes.mdx
+5
-1
@@ -77,7 +77,7 @@ curl -X POST https://backend.composio.dev/api/v3.1/auth_configs \
77
78
## Set scopes with your own OAuth app
79
80
-When you bring your own OAuth credentials, put `scopes` alongside the client ID and secret. Make sure your OAuth app has those scopes approved in the provider's portal.
80
+Use your own OAuth app when a tool needs a scope that Composio's managed app isn't approved for. When you bring your own OAuth credentials, put `scopes` alongside the client ID and secret. Make sure your OAuth app has those scopes approved in the provider's portal.
81
82
<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
83
<Tab value="Python">
@@ -186,6 +186,10 @@ curl -X PATCH https://backend.composio.dev/api/v3.1/auth_configs/ac_1234 \
186
Changing scopes affects new connections only. Users with an existing [connected account](/docs/authentication#behind-the-scenes) keep the scopes they already granted until they reconnect. To apply new scopes to a current user, have them re-authenticate.
187
</Callout>
188
189
+## Tools that need a different auth scheme
190
+
191
+Some tools work only under certain auth schemes. When a tool isn't available under your auth config's scheme, create an auth config for the toolkit with a scheme the tool supports, and have users connect through it. A toolkit lists its schemes in `auth_config_details`: see [Discover the required fields](/docs/authentication/programmatic-auth-configs#discover-the-required-fields) and [Other auth types](/docs/authentication/programmatic-auth-configs#other-auth-types).
192
+
193
## Use the auth config in a session
194
195
Setting scopes on an auth config does nothing until a session uses it. Pass the auth config ID to `authConfigs` (keyed by toolkit) when you create the session, and the session requests your scopes when the user connects that toolkit.