Authentication

Custom Auth Configs

Guide to customizing auth configs for a toolkit

Many toolkits support a level of customization for the auth config, specifically OAuth applications.

This guide will walk you through the process of customizing the auth config for toolkits where you can configure the developer app.

Creating a custom auth config

Some apps, like PostHog, Hubspot, Linear, etc. allow customizing the auth config for your usage.

You’ll need to customize the auth config in cases where you want to add in a different field than the default. This could be the subdomain, base URL, client ID, client secret, etc.

You may change the subdomain for the PostHog toolkit to match your own instance.

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

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 your provider’s OAuth configuration page.

Examples for Google and GitHub:

Google 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:

https://backend.composio.dev/api/v3/toolkits/auth/callback
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. Select the scopes to request from users. Default scopes are pre-filled for most apps.
  3. Add the OAuth client ID and client secret. Keep the redirect URL as is for now!
  4. Click “Create Integration” once done!

As usual, copy and use the auth config ID starting with ac_ in your application code via a secret manager.

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

1# Create a new connected account
2connection_request = composio.connected_accounts.initiate(
3    user_id="user_id",
4    auth_config_id="ac_1234",
5)
6print(connection_request)
7
8# Wait for the connection to be established
9connected_account = connection_request.wait_for_connection()
10print(connected_account)

By default the users will see an OAuth screen like the one below:

Composio's Domain in OAuth Consent Screen

The OAuth redirect URL is surfaced in some OAuth providers’ consent screens. This may cause confusion for some users as that URL is not of the same domain as the application.

To remediate this:

1

Set the Authorized Redirect URI

Specify the Authorized Redirect URI to your own domain in the OAuth configuration. For example:

https://yourdomain.com/api/composio-redirect
2

Create a redirect logic

Create a redirect logic, either through your DNS or in your application to redirect that endpoint to https://backend.composio.dev/api/v3/toolkits/auth/callback

Example: API Route for OAuth Redirect

1from fastapi import FastAPI
2from fastapi.responses import RedirectResponse
3
4from composio import Composio
5
6# Create a FastAPI app
7app = FastAPI()
8
9# Create a Composio client
10composio = Composio()
11
12
13@app.get("/authorize/{toolkit}")
14def authorize_app(toolkit: str):
15    # retrieve the user id from your app
16    user_id = "<user_id>"
17
18    # retrieve the auth config id from your app
19    auth_config_id = "<auth_config_id>"
20
21    # initiate the connection request
22    connection_request = composio.connected_accounts.initiate(
23        user_id=user_id,
24        auth_config_id=auth_config_id,
25    )
26    return RedirectResponse(url=connection_request.redirect_url)
3

Create the auth config

Specify your custom redirect URI in the auth config settings!

With this setup, you can use https://yourdomain.com/api/composio-redirect as your OAuth redirect URI, which will create a better user experience by keeping users on your domain during the OAuth flow.

The custom OAuth config allows you to use your own domain in the OAuth consent screen instead of Composio’s domain. Here’s the core difference:

Key Benefits:

  • Custom Domain: Users see your domain in OAuth consent screens, not Composio’s
  • Same Security: Your domain just forwards the OAuth callback - no token handling
  • Better UX: Maintains brand consistency throughout the auth flow

The custom redirect endpoint is a simple passthrough that preserves all OAuth parameters while keeping users on your domain.