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

# Custom Auth Configs

> Customize auth configs for any toolkit

> [!NOTE]
>
> If you're building an agent, we recommend using [sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md) instead. See [Managed vs custom auth](https://composio-preview.mintlify.site/docs/authentication/custom-app-vs-managed-app.md) for how to use custom credentials with sessions.

Auth configs control how users authenticate with a toolkit. By default, Composio provides managed credentials for many toolkits. You create a custom auth config when the defaults don't fit your needs.

## When to create a custom auth config

| Reason | Example |
| - | - |
| **Toolkit has no managed auth** | PostHog, Tavily, Perplexity: you must provide your own credentials |
| **White-labeling** | Show your app name on OAuth consent screens instead of "Composio". See [White-labeling](https://composio-preview.mintlify.site/docs/auth-configuration/white-labeling.md) |
| **Rate limits and quota** | Composio's default OAuth app shares quota across all users. Your own app gets a dedicated quota |
| **Custom scopes** | You need permissions beyond what Composio's default app has approved |
| **Custom instance or subdomain** | Connecting to a self-hosted or regional variant (e.g., custom Salesforce subdomain) |

## Creating a custom auth config

To create a custom auth config, click **Create Auth Config** in your dashboard, then navigate to **Authentication management** → **Manage authentication with custom credentials**.

You'll need to customize the auth config when you want to use different values than the defaults - such as your own subdomain, base URL, client ID, client secret, etc.

> [tab] Example: PostHog
>
> You may change the subdomain for the PostHog toolkit to match your own instance.
>
> ![PostHog Auth Config Settings](https://mintcdn.com/composio-preview/8QmhU-UXaqTdWL9_/images/custom-auth-posthog.png?fit=max\&auto=format\&n=8QmhU-UXaqTdWL9_\&q=85\&s=066d58f330a846a74bdc15fac5643e40)
>
> PostHog Auth Config Settings

> [tab] Example: Hubspot
>
> For Hubspot you may customize everything here. For each auth scheme there is a different set of fields.
>
> If you choose to use your own developer app for the OAuth2 scheme, you will have to provide the client ID and client secret.
>
> ![Hubspot Auth Config Settings](https://mintcdn.com/composio-preview/8QmhU-UXaqTdWL9_/images/custom-auth-hubspot.png?fit=max\&auto=format\&n=8QmhU-UXaqTdWL9_\&q=85\&s=98db2f634972ad47f4f78b0cbb97dcbc)
>
> Hubspot Auth Config Settings

Toolkits that support OAuth2 allow using your own developer app. This is the recommended approach for most cases.

> [!NOTE]
>
> **Use your own developer app!**
>
> We recommend using your own developer app for the OAuth2 scheme as it is more suited for production usage with many users and more granular control over scopes.
>
> However, getting OAuth approvals takes time, so Composio provides a default developer app!

## OAuth2 Auth Configs

**1. Generate the OAuth Client ID and Client Secret**

To set up a custom OAuth config, you'll need the OAuth Client ID and Client Secret.

You can generate the client ID and client secret from the toolkit's OAuth configuration page.

Examples for Google and GitHub:

> [tab] Google
>
> ![Google OAuth Configuration](https://mintcdn.com/composio-preview/8QmhU-UXaqTdWL9_/images/google-oauth-config.png?fit=max\&auto=format\&n=8QmhU-UXaqTdWL9_\&q=85\&s=3074a8eeb1f38bed3162981b6732b229)
>
> Google OAuth Configuration

> [tab] GitHub
>
> ![GitHub OAuth Configuration](https://mintcdn.com/composio-preview/8QmhU-UXaqTdWL9_/images/github-oauth-config.png?fit=max\&auto=format\&n=8QmhU-UXaqTdWL9_\&q=85\&s=f85a1d352a9c0cfd4e7a72c4edffca9d)
>
> GitHub OAuth Configuration

**2. Set the Authorized Redirect URI**

When creating your OAuth app, make sure to configure the Authorized Redirect URI to point to the Composio callback URL below:

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

> [!NOTE]
>
> **Match the redirect URI**
>
> The redirect URI in your OAuth app must exactly match `oauth_redirect_uri` in your Composio auth config. Some toolkit defaults still use `https://backend.composio.dev/api/v1/auth-apps/add`, which remains supported. To use the URL above, set it explicitly in both places to avoid `redirect_uri_mismatch` errors.

**3. Create the auth config**

Once you have the OAuth credentials, you can add them to the auth config in the dashboard.

1. Select the OAuth2 scheme.
2. Toggle on **Use your own developer credentials**.
3. Enter the OAuth client ID and client secret for your developer app.
4. Set **Redirect URI** to the URL registered in your OAuth app.
5. Click Create!

![Auth Config Settings](https://mintcdn.com/composio-preview/8QmhU-UXaqTdWL9_/images/integration-step-3-0.png?fit=max\&auto=format\&n=8QmhU-UXaqTdWL9_\&q=85\&s=fda04f0c05be015939e2fcbbe9f5ddf7)

Auth Config Settings

This auth config is now ready to be used in your application!

> [tab] Python
>
> ```python theme={null}
> # Create a new connected account
> connection_request = composio.connected_accounts.initiate(
>     user_id="user_123",
>     auth_config_id="ac_1234",
> )
> print(connection_request.redirect_url)
>
> # Wait for the connection to be established
> connected_account = connection_request.wait_for_connection()
> print(connected_account)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const userId = 'user_123';
> const connReq = await composio.connectedAccounts.initiate(userId, "ac_1234");
>
> console.log(connReq.redirectUrl);
>
> const connection = await composio.connectedAccounts.waitForConnection(
>   connReq.id
> );
>
> console.log(connection);
> ```

> [tab] API
>
> ```bash theme={null}
> # Create a new connected account
> RESPONSE=$(curl -s -X POST https://backend.composio.dev/api/v3.1/connected_accounts \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"auth_config": {"id": "ac_1234"}, "connection": {"user_id": "user_123"}}')
> echo "$RESPONSE" | jq -r '.redirect_url'
> CONNECTED_ACCOUNT_ID=$(echo "$RESPONSE" | jq -r '.id')
>
> # After the user finishes the redirect, check the connection
> curl -X GET https://backend.composio.dev/api/v3.1/connected_accounts/$CONNECTED_ACCOUNT_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

## Next

> [card] [Connected accounts](https://composio-preview.mintlify.site/docs/auth-configuration/connected-accounts.md)
>
> Manage and monitor user connections to toolkits
