> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Controlling scopes

> Override the default OAuth scopes Composio requests for a toolkit

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](https://composio-preview.mintlify.site/docs/authentication#behind-the-scenes), then [pass that auth config to a session](#use-the-auth-config-in-a-session) so the session requests your scopes when users connect.

> [!NOTE]
>
> 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

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.

> [!NOTE]
>
> Scope recommendations and grant-context APIs are experimental. Review the recommendation before using it in your auth config.

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.

> [tab] Python
>
> ```python theme={null}
> 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"},
>     },
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
> const authConfig = await composio.authConfigs.create('hubspot', {
>   type: 'use_composio_managed_auth',
>   name: 'HubSpot',
>   credentials: { scopes: 'sales-email-read,tickets' },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/auth_configs \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "toolkit": {"slug": "hubspot"},
>     "auth_config": {
>       "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.

> [tab] Python
>
> ```python theme={null}
> import os
> from typing import cast
> from composio.client.types import auth_config_create_params as auth_types
>
> auth_config = composio.auth_configs.create(
>     toolkit="github",
>     options={
>         "type": "use_custom_auth",
>         "auth_scheme": "OAUTH2",
>         "name": "GitHub",
>         # The generated credentials type omits OAuth client fields accepted by the API.
>         "credentials": cast(auth_types.AuthConfigUnionMember1Credentials, {
>             "client_id": os.environ["GITHUB_CLIENT_ID"],
>             "client_secret": os.environ["GITHUB_CLIENT_SECRET"],
>             "scopes": "repo,read:org",
>         }),
>     },
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
> const authConfig = await composio.authConfigs.create('github', {
>   type: 'use_custom_auth',
>   authScheme: 'OAUTH2',
>   name: 'GitHub',
>   credentials: {
>     client_id: process.env.GITHUB_CLIENT_ID!,
>     client_secret: process.env.GITHUB_CLIENT_SECRET!,
>     scopes: 'repo,read:org',
>   },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/auth_configs \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "toolkit": {"slug": "github"},
>     "auth_config": {
>       "type": "use_custom_auth",
>       "authScheme": "OAUTH2",
>       "name": "GitHub",
>       "credentials": {
>         "client_id": "'"$GITHUB_CLIENT_ID"'",
>         "client_secret": "'"$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.

> [tab] Python
>
> The high-level `auth_configs.update()` helper does not forward `scopes` or `user_scopes`. Use the public generated client for these fields:
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio()
> composio.client.auth_configs.update(
>     "ac_1234",
>     type="default",
>     scopes="repo,read:org,read:user",
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> await composio.authConfigs.update('ac_1234', {
>   type: 'default',
>   scopes: 'repo,read:org,read:user',
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X PATCH https://backend.composio.dev/api/v3.1/auth_configs/ac_1234 \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"type": "default", "scopes": "repo,read:org,read:user"}'
> ```

> [!WARNING]
>
> Changing scopes affects new connections only. Users with an existing [connected account](https://composio-preview.mintlify.site/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.

## 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.

> [tab] Python
>
> ```python theme={null}
> session = composio.create(
>     user_id="user_123",
>     auth_configs={"github": auth_config.id},
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const authConfig = { id: 'ac_your_github_config' };
> const session = await composio.create('user_123', {
>   authConfigs: { github: authConfig.id },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_123", "auth_configs": {"github": "ac_your_github_config"}}'
> ```

## Next

> [card] [White-labeling authentication](https://composio-preview.mintlify.site/docs/authentication/white-labeling-authentication.md)
>
> Remove Composio branding from your auth flows
