Scopes apply to OAuth toolkits. Toolkits that authenticate with API keys or bearer tokens don’t have scopes to set.
Choose scopes for your tools
Usecomposio.toolkits.recommend_scopes("gmail", tools=["GMAIL_SEND_EMAIL"]) in Python or await composio.toolkits.recommendScopes('gmail', { tools: ['GMAIL_SEND_EMAIL'] }) in TypeScript to find scopes for the tools your agent needs. The response includes a least-privilege set, a set with the fewest scopes, and conditional scopes. Pass available_scopes (Python) or availableScopes (TypeScript) to constrain recommendations to scopes your OAuth app can request.
Recommendations can depend on account type or other grant contexts. Inspect the supported dimensions and defaults with composio.toolkits.list_grant_contexts("gmail") in Python or await composio.toolkits.listGrantContexts('gmail') in TypeScript, then pass your selections as grant_context or grantContext when requesting scopes.
Scope recommendations and grant-context APIs are experimental. Review the recommendation before using it in your auth config.
required_scopes (Python) or requiredScopes (TypeScript): scopes the auth method always requests, regardless of tool-specific scopes. Auth fields expose user_visible or userVisible to indicate whether the hosted connection flow displays them. These fields may be absent when the API does not provide them.
Set scopes with Composio managed auth
Pass ascopes field in credentials to override the defaults while still using Composio’s managed OAuth app. Give scopes as a comma-separated string.
- Python
- TypeScript
- API
Set scopes with your own OAuth app
When you bring your own OAuth credentials, putscopes alongside the client ID and secret. Make sure your OAuth app has those scopes approved in the provider’s portal.
- Python
- TypeScript
- API
Update scopes on an existing config
Change the scopes on an auth config you already created without recreating it.- Python
- TypeScript
- API
The high-level
auth_configs.update() helper does not forward scopes or user_scopes. Use the public generated client for these fields:Use the auth config in a session
Setting scopes on an auth config does nothing until a session uses it. Pass the auth config ID toauthConfigs (keyed by toolkit) when you create the session, and the session requests your scopes when the user connects that toolkit.
- Python
- TypeScript
- API