Controlling scopes

Scopes are the permissions an OAuth toolkit grants your app: read email, write to a repo, manage calendar events. Composio requests a sensible set of default scopes for each toolkit, so most apps never set scopes at all. Override them when the defaults grant too much or too little: to follow least privilege, or to reach an API the defaults don't cover.

You control scopes on an auth config, then pass that auth config to a session so the session requests your scopes when users connect.

Choose scopes for your tools

Use composio.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.

Toolkit auth details also expose 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 a scopes field in credentials to override the defaults while still using Composio's managed OAuth app. Give scopes as a comma-separated string.

from composio import Composio

composio = Composio()

auth_config = composio.auth_configs.create(
    toolkit="hubspot",
    options={
        "type": "use_composio_managed_auth",
        "name": "HubSpot",
        "credentials": {"scopes": "sales-email-read,tickets"},
    },
)

Set scopes with your own OAuth app

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.

import os

auth_config = composio.auth_configs.create(
    toolkit="github",
    options={
        "type": "use_custom_auth",
        "auth_scheme": "OAUTH2",
        "name": "GitHub",
        "credentials": {
            "client_id": os.environ["GITHUB_CLIENT_ID"],
            "client_secret": os.environ["GITHUB_CLIENT_SECRET"],
            "scopes": "repo,read:org",
        },
    },
)

Update scopes on an existing config

Change the scopes on an auth config you already created without recreating it.

composio.auth_configs.update(
    "ac_1234",
    {"type": "default", "scopes": "repo,read:org,read:user"},
)

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 to authConfigs (keyed by toolkit) when you create the session, and the session requests your scopes when the user connects that toolkit.

session = composio.create(
    user_id="user_123",
    auth_configs={"github": auth_config.id},
)

Next