Using custom auth configuration

You create a custom auth config when you need to provide your own credentials for a toolkit. Common reasons:

Toolkit has no managed auth: PostHog, Tavily, Perplexity, etc. require your own credentials
White-labeling: Show your app name on OAuth consent screens instead of "Composio". See White-labeling authentication
Rate limits: 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: Connecting to a self-hosted or regional variant (e.g., custom Salesforce subdomain)

Check if a toolkit needs custom credentials

In the Composio platform, go to "All Toolkits" and select the toolkit. If it shows no Composio managed auth schemes, you'll need to create an auth config. You can also browse the full list on the managed auth page.

Create an auth config

Go to Authentication management in the dashboard
Click Create Auth Config
Select the toolkit
Choose the auth scheme (OAuth2, API Key, etc.)
Enter your credentials (client ID, client secret, API key, etc.)
Click Create

Copy the auth config ID (e.g., ac_1234abcd).

Step-by-step guides for popular toolkits: Google | GitHub | Slack | HubSpot | All toolkits

Use in your session

Pass your auth config ID when creating a session:

session = composio.create(
    user_id="user_123",
    auth_configs={
        "posthog": "ac_your_posthog_config"
    }
)

const session = await composio.create("user_123", {
  authConfigs: {
    posthog: "ac_your_posthog_config",
  },
});

Your session will now use this auth config when users connect to this toolkit.

Using custom auth configuration

What to read next

When to use your own developer credentials

White-labeling authentication

Authentication overview

Configuring sessions

On this page