White-labeling authentication

White-labeling lets you use your own OAuth apps instead of Composio's. Users will see your app name on consent screens instead of "Composio".

By default, OAuth screens show Composio's branding. With white-labeling, they'll see your app name and logo.

Create an OAuth app

Create a developer app in the toolkit's developer portal. You'll need the client ID and client secret. Set the callback URL to:

https://backend.composio.dev/api/v3/toolkits/auth/callback

For step-by-step guides on creating OAuth apps for some toolkits, see composio.dev/auth.

Create auth config

Create an auth config in the Composio dashboard:

Go to Authentication management → Create Auth Config
Select the toolkit (e.g., GitHub)
Choose OAuth2 scheme
Enter your Client ID and Client Secret
Select the scopes you need
Click Create

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

For detailed instructions with screenshots, see Custom auth configs.

Use in Tool Router

Pass your auth config ID in the session:

session = composio.create(
    user_id="user_123",
    auth_configs={
        "github": "ac_your_github_config"
    },
)

const const session: ToolRouterSession<unknown, unknown, OpenAIProvider>session = await const composio: Composio<OpenAIProvider>composio.Composio<OpenAIProvider>.create: (userId: string, routerConfig?: ToolRouterCreateSessionConfig) => Promise<ToolRouterSession<unknown, unknown, OpenAIProvider>>Creates a new tool router session for a user.
@paramuserId The user id to create the session for@paramconfig The config for the tool router session@returnsThe tool router session@example```typescript
import { Composio } from '@composio/core';

const composio = new Composio();
const userId = 'user_123';

const session = await composio.create(userId, {
 manageConnections: true,
});

console.log(session.sessionId);
console.log(session.url);
console.log(session.tools());
```create("user_123", {
  authConfigs?: Record<string, string> | undefinedauthConfigs: {
    github: stringgithub: "ac_your_github_config",
  },
});

When users connect GitHub, they'll see your OAuth app's name and logo on the consent screen.

Mixing custom and Composio-managed auth

You can white-label some toolkits while using Composio's managed credentials for others:

session = composio.create(
    user_id="user_123",
    auth_configs={
        "github": "ac_your_github_config",
        "slack": "ac_your_slack_config",
        # gmail, linear, etc. use Composio managed auth
    },
)

const const session: ToolRouterSession<unknown, unknown, OpenAIProvider>session = await const composio: Composio<OpenAIProvider>composio.Composio<OpenAIProvider>.create: (userId: string, routerConfig?: ToolRouterCreateSessionConfig) => Promise<ToolRouterSession<unknown, unknown, OpenAIProvider>>Creates a new tool router session for a user.
@paramuserId The user id to create the session for@paramconfig The config for the tool router session@returnsThe tool router session@example```typescript
import { Composio } from '@composio/core';

const composio = new Composio();
const userId = 'user_123';

const session = await composio.create(userId, {
 manageConnections: true,
});

console.log(session.sessionId);
console.log(session.url);
console.log(session.tools());
```create("user_123", {
  authConfigs?: Record<string, string> | undefinedauthConfigs: {
    github: stringgithub: "ac_your_github_config",
    slack: stringslack: "ac_your_slack_config",
    // gmail, linear, etc. use Composio managed auth
  },
});

Custom redirect domain

When users authenticate, they briefly see backend.composio.dev in their browser URL. Composio needs to receive the OAuth callback to capture and store the authentication tokens.

If you need to hide this URL (for enterprise compliance or complete white-labeling), you can proxy the redirect through your own domain:

Set your OAuth app's redirect URI to your domain:

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

Create an endpoint that forwards the OAuth callback to Composio:

from fastapi import FastAPI, Request
from fastapi.responses import RedirectResponse

app = FastAPI()

@app.get("/api/composio-redirect")
def composio_redirect(request: Request):
    # Forward all OAuth parameters to Composio
    composio_url = "https://backend.composio.dev/api/v3/toolkits/auth/callback"
    return RedirectResponse(url=f"{composio_url}?{request.url.query}")

// pages/api/composio-redirect.ts (Next.js)
import type { NextApiRequest, 
type NextApiResponse<Data = any> = ServerResponse<IncomingMessage> & {
    send: Send<Data>;
    json: Send<Data>;
    status: (statusCode: number) => NextApiResponse<Data>;
    redirect(url: string): NextApiResponse<Data>;
    redirect(status: number, url: string): NextApiResponse<Data>;
    setDraftMode: (options: {
        enable: boolean;
    }) => NextApiResponse<Data>;
    setPreviewData: (data: object | string, options?: {
        maxAge?: number;
        path?: string;
    }) => NextApiResponse<Data>;
    clearPreviewData: (options?: {
        path?: string;
    }) => NextApiResponse<Data>;
    revalidate: (urlPath: string, opts?: {
        unstable_onlyGenerated?: boolean;
    }) => Promise<void>;
}Next `API` route responseNextApiResponse } from "next";

export default function function handler(req: NextApiRequest, res: NextApiResponse): voidhandler(req: NextApiRequestreq: NextApiRequest, res: NextApiResponseres: 
type NextApiResponse<Data = any> = ServerResponse<IncomingMessage> & {
    send: Send<Data>;
    json: Send<Data>;
    status: (statusCode: number) => NextApiResponse<Data>;
    redirect(url: string): NextApiResponse<Data>;
    redirect(status: number, url: string): NextApiResponse<Data>;
    setDraftMode: (options: {
        enable: boolean;
    }) => NextApiResponse<Data>;
    setPreviewData: (data: object | string, options?: {
        maxAge?: number;
        path?: string;
    }) => NextApiResponse<Data>;
    clearPreviewData: (options?: {
        path?: string;
    }) => NextApiResponse<Data>;
    revalidate: (urlPath: string, opts?: {
        unstable_onlyGenerated?: boolean;
    }) => Promise<void>;
}Next `API` route responseNextApiResponse) {
  // Forward all OAuth parameters to Composio
  const const composioUrl: "https://backend.composio.dev/api/v3/toolkits/auth/callback"composioUrl = "https://backend.composio.dev/api/v3/toolkits/auth/callback";
  const const params: URLSearchParamsparams = new var URLSearchParams: new (init?: string[][] | Record<string, string> | string | URLSearchParams) => URLSearchParamsThe **`URLSearchParams`** interface defines utility methods to work with the query string of a URL.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/URLSearchParams)URLSearchParams(req: NextApiRequestreq.
NextApiRequest.query: Partial<{
    [key: string]: string | string[];
}>Object of `query` values from urlquery as type Record<K extends keyof any, T> = { [P in K]: T; }Construct a type with a set of properties K of type TRecord<string, string>);
  res: NextApiResponseres.function redirect(status: number, url: string): NextApiResponse<any> (+1 overload)redirect(302, `${const composioUrl: "https://backend.composio.dev/api/v3/toolkits/auth/callback"composioUrl}?${const params: URLSearchParamsparams.URLSearchParams.toString(): stringtoString()}`);
}

Update your auth config in the Composio dashboard to use your custom redirect URI.

This makes the OAuth flow go through your domain first, then to Composio for token storage.