Authentication

Custom Auth Configs

Guide to using customising auth configs for a toolkit

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

This guide will walk you through the process of customising 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 OAuth2 scheme as it is suited more 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/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!

1const connReq = await composio.connectedAccounts.initiate(userId, "ac_1234");
2
3console.log(connReq.redirectUrl);
4
5const connection = await composio.connectedAccounts.waitForConnection(
6connReq.id
7);
8
9console.log(connection);

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 the 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/callback

Example: API Route for OAuth Redirect

1import type { NextApiRequest, NextApiResponse } from 'next';
2
3export default function handler(req: NextApiRequest, res: NextApiResponse) {
4  // The target Composio endpoint that handles OAuth callbacks
5  const composioEndpoint = 'https://backend.composio.dev/api/v3/toolkits/callback';
6
7// Extract and preserve all query parameters
8const queryParams = new URLSearchParams();
9Object.entries(req.query).forEach(([key, value]) => {
10if (typeof value === 'string') {
11queryParams.append(key, value);
12}
13});
14
15// Redirect to Composio with all query parameters intact
16const redirectUrl = `${composioEndpoint}?${queryParams.toString()}`;
17res.redirect(302, redirectUrl);
18}
3

Create the auth config

Specify the 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.