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

# Programmatic auth configs

> Create auth configs in code and pass them to a session

An [auth config](https://composio-preview.mintlify.site/docs/authentication#behind-the-scenes) is a blueprint for how a toolkit authenticates: the method, scopes, and credentials. Most of the time you create one in the [dashboard](https://dashboard.composio.dev/~/project/auth-configs?utm_source=docs\&utm_medium=content\&utm_campaign=docs-programmatic-auth-configs) and reuse it. Create them in code when you provision auth dynamically: a config per customer, per environment, or spun up and torn down as part of your app's lifecycle.

`composio.authConfigs.create()` returns an auth config ID like `ac_xxxxxxxx`. Store that ID, then [pass it to a session](#use-the-auth-config-in-a-session) so the session authenticates with it.

## Composio managed auth

For OAuth2 toolkits, Composio maintains a managed app so you can create an auth config without bringing your own credentials. This is the fastest way to start.

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio()
>
> auth_config = composio.auth_configs.create(
>     toolkit="github",
>     options={"type": "use_composio_managed_auth", "name": "GitHub"},
> )
>
> print(auth_config.id)  # ac_xxxxxxxx
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
> const authConfig = await composio.authConfigs.create('github', {
>   type: 'use_composio_managed_auth',
>   name: 'GitHub',
> });
>
> console.log(authConfig.id); // ac_xxxxxxxx
> ```

> [tab] API
>
> ```bash theme={null}
> curl -s -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_composio_managed_auth", "name": "GitHub"}}' \
>   | jq -r '.auth_config.id'  # ac_xxxxxxxx
> ```

## Your own OAuth2 credentials

Bring your own OAuth app to show your branding on consent screens, request custom scopes, or get a dedicated rate-limit quota. Register the app in the provider's developer portal, set its authorized redirect URI to Composio's callback, then pass the client ID and secret.

```text theme={null}
https://backend.composio.dev/api/v3/toolkits/auth/callback
```

> [tab] Python
>
> ```python theme={null}
> import os
> from typing import cast
> from composio import Composio
> from composio.client.types import auth_config_create_params as auth_types
>
> composio = Composio()
>
> auth_config = composio.auth_configs.create(
>     toolkit="notion",
>     options={
>         "type": "use_custom_auth",
>         "auth_scheme": "OAUTH2",
>         "name": "Notion",
>         # The generated credentials type omits OAuth client fields accepted by the API.
>         "credentials": cast(auth_types.AuthConfigUnionMember1Credentials, {
>             "client_id": os.environ["NOTION_CLIENT_ID"],
>             "client_secret": os.environ["NOTION_CLIENT_SECRET"],
>             "oauth_redirect_uri": "https://backend.composio.dev/api/v3/toolkits/auth/callback",
>         }),
>     },
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
> const authConfig = await composio.authConfigs.create('notion', {
>   type: 'use_custom_auth',
>   authScheme: 'OAUTH2',
>   name: 'Notion',
>   credentials: {
>     client_id: process.env.NOTION_CLIENT_ID!,
>     client_secret: process.env.NOTION_CLIENT_SECRET!,
>     oauth_redirect_uri: 'https://backend.composio.dev/api/v3/toolkits/auth/callback',
>   },
> });
> ```

> [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": "notion"},
>     "auth_config": {
>       "type": "use_custom_auth",
>       "authScheme": "OAUTH2",
>       "name": "Notion",
>       "credentials": {
>         "client_id": "'"$NOTION_CLIENT_ID"'",
>         "client_secret": "'"$NOTION_CLIENT_SECRET"'",
>         "oauth_redirect_uri": "https://backend.composio.dev/api/v3/toolkits/auth/callback"
>       }
>     }
>   }'
> ```

> [!NOTE]
>
> Set `oauth_redirect_uri` to the exact URL registered in your provider's OAuth app. Some toolkit defaults still use the supported legacy endpoint `https://backend.composio.dev/api/v1/auth-apps/add`. If you omit `oauth_redirect_uri`, register the toolkit's default URL with your provider. When you [route the callback through your own domain](https://composio-preview.mintlify.site/docs/authentication/white-labeling-authentication.md#routing-the-callback-through-your-domain), set your custom URL in both places.

## Other auth types

Toolkits that use API keys, bearer tokens, basic auth, or no auth follow the same call. Set `auth_scheme` to the toolkit's scheme and put the required fields in `credentials`. For a toolkit whose key the user supplies at connect time, pass empty `credentials`.

> [tab] Python
>
> ```python theme={null}
> auth_config = composio.auth_configs.create(
>     toolkit="perplexityai",
>     options={
>         "type": "use_custom_auth",
>         "auth_scheme": "API_KEY",
>         "name": "Perplexity AI",
>         "credentials": {},
>     },
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
> const authConfig = await composio.authConfigs.create('perplexityai', {
>   type: 'use_custom_auth',
>   authScheme: 'API_KEY',
>   name: 'Perplexity AI',
>   credentials: {},
> });
> ```

> [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": "perplexityai"}, "auth_config": {"type": "use_custom_auth", "authScheme": "API_KEY", "name": "Perplexity AI", "credentials": {}}}'
> ```

## Use the auth config in a session

Creating an auth config does not change which credentials a session uses. Pass the auth config ID to `authConfigs` (keyed by toolkit) when you create the session, and the session authenticates that toolkit with your config. Toolkits you leave out keep using Composio managed auth.

> [tab] Python
>
> ```python theme={null}
> session = composio.sessions.create(
>     user_id="user_123",
>     auth_configs={"notion": 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_notion_config' };
> const session = await composio.create('user_123', {
>   authConfigs: { notion: 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": {"notion": "ac_your_notion_config"}}'
> ```

See [Configuring sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md#custom-auth-configs) for how `authConfigs` interacts with account selection and precedence.

## Find auth configs

You can fetch up to 200 auth configs per request. Set `limit` to `200` when listing auth configs to retrieve up to that many at once. Paginate through the results if you have more than 200 matching configs.

Filter auth configs by name or ID with `search` in either SDK or the API. Disabled configs are excluded by default; set `showDisabled` (`show_disabled` in Python) to include them. Auth config responses use `id` as their canonical identifier.

> [tab] Python
>
> ```python theme={null}
> configs = composio.auth_configs.list(search="github", show_disabled=True)
>
> for config in configs.items:
>     print(config.id)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
> const configs = await composio.authConfigs.list({
>   search: 'github',
>   showDisabled: true,
> });
>
> for (const config of configs.items) {
>   console.log(config.id);
> }
> ```

> [tab] API
>
> ```bash theme={null}
> curl -s -X GET "https://backend.composio.dev/api/v3.1/auth_configs?search=github&show_disabled=true" \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   | jq -r '.items[].id'
> ```

## Discover the required fields

Different schemes need different credential fields. To build the `credentials` object dynamically, ask the toolkit which fields it requires for a given scheme before you create the config.

> [tab] Python
>
> ```python theme={null}
> fields = composio.toolkits.get_auth_config_creation_fields(
>     toolkit="notion",
>     auth_scheme="OAUTH2",
>     required_only=True,
> )
> print(fields)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio();
> const fields = await composio.toolkits.getAuthConfigCreationFields('notion', 'OAUTH2', {
>   requiredOnly: true,
> });
>
> console.log(fields);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -s -X GET https://backend.composio.dev/api/v3.1/toolkits/notion \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   | jq '.auth_config_details[] | select(.mode == "OAUTH2") | .fields.auth_config_creation.required'
> ```

## Next

> [card] [Controlling scopes](https://composio-preview.mintlify.site/docs/authentication/controlling-scopes.md)
>
> Override the default OAuth scopes Composio requests for a toolkit
