Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: consolidate white-labeling and custom auth config documentation
Sushmitha Mallesh13482bc8891c
diff --git a/docs/content/docs/auth-configuration/custom-auth-configs.mdx b/docs/content/docs/auth-configuration/custom-auth-configs.mdxindex 74742c261..c78329991 100644--- a/docs/content/docs/auth-configuration/custom-auth-configs.mdx+++ b/docs/content/docs/auth-configuration/custom-auth-configs.mdx@@ -9,9 +9,17 @@ llmGuardrails: "direct-execution"If you're building an agent, we recommend using [sessions](/docs/configuring-sessions) instead. See [Using custom auth configs](/docs/using-custom-auth-configuration) for how to use custom credentials with sessions.</Callout>-Many toolkits support a level of customization for the auth config, specifically OAuth applications.+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.-This guide will walk you through the process of customizing the auth config for toolkits where you can configure your own developer app.+## 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](/docs/auth-configuration/white-labeling) |+| **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@@ -50,7 +58,7 @@ However, getting OAuth approvals takes time, so Composio provides a default deveTo 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.+You can generate the client ID and client secret from the toolkit's OAuth configuration page.Examples for Google and GitHub:@@ -80,8 +88,8 @@ https://backend.composio.dev/api/v3/toolkits/auth/callbackOnce 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 for your developer app. Keep the redirect URL as is for now!+2. Toggle on **Use your own developer credentials**.+3. Enter the OAuth client ID and client secret for your developer app.4. Click Create!<Figure src="/images/integration-step-3-0.png" alt="Auth Config Settings" caption="Auth Config Settings" size="sm" />@@ -124,137 +132,6 @@ console.log(connection);</Tab></Tabs>-### White-labeling the OAuth Consent Screen--By default the users will see an OAuth screen like the one below:--<Figure src="/images/oauth-branding.png" alt="Composio's Domain in OAuth Consent Screen" caption="Composio's Domain in OAuth Consent Screen" size="sm" />--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:--<Steps>-<Step>-<StepTitle>Set the Authorized Redirect URI</StepTitle>--Specify the Authorized Redirect URI to your own domain in the OAuth configuration.-For example:-```-https://yourdomain.com/api/composio-redirect-```-</Step>--<Step>-<StepTitle>Create a redirect logic</StepTitle>--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**--<Tabs groupId="language" items={['Python', 'TypeScript']} persist>- <Tab value="Python">-```python-from fastapi import FastAPI-from fastapi.responses import RedirectResponse--from composio import Composio--# Create a FastAPI app-app = FastAPI()--# Create a Composio client-composio = Composio()--[email protected]("/authorize/{toolkit}")-def authorize_app(toolkit: str):- # retrieve the user id from your app- user_id = "<user_id>"-- # retrieve the auth config id from your app- auth_config_id = "<auth_config_id>"-- # initiate the connection request- connection_request = composio.connected_accounts.initiate(- user_id=user_id,- auth_config_id=auth_config_id,- )- return RedirectResponse(url=connection_request.redirect_url)-```- </Tab>- <Tab value="TypeScript">-```typescript-import type { NextApiRequest, NextApiResponse } from 'next';--export default function handler(req: NextApiRequest, res: NextApiResponse) {- // The target Composio endpoint that handles OAuth callbacks- const composioEndpoint = 'https://backend.composio.dev/api/v3/toolkits/auth/callback';-- // Extract and preserve all query parameters- const queryParams = new URLSearchParams();- Object.entries(req.query).forEach(([key, value]) => {- if (typeof value === 'string') {- queryParams.append(key, value);- }- });-- // Redirect to Composio with all query parameters intact- const redirectUrl = `${composioEndpoint}?${queryParams.toString()}`;- res.redirect(302, redirectUrl);-}-```- </Tab>-</Tabs>-</Step>--<Step>-<StepTitle>Create the auth config</StepTitle>--Specify your custom redirect URI in the auth config settings!--<Figure src="/images/custom-redirect-uri.png" alt="Auth Config Settings" caption="Auth Config Settings" size="sm" />-</Step>-</Steps>--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.--<Accordions>-<Accordion title="How does this work?">--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:--```mermaid-flowchart TD- A[Your App initiates OAuth] --> B[User redirected to OAuth Provider]- B --> C{Redirect URI Configuration}-- C -->|Direct Setup| D[Provider redirects to<br/>backend.composio.dev]- C -->|Custom Domain| E[Provider redirects to<br/>yourdomain.com/api/composio-redirect]-- E --> F[Your endpoint forwards to<br/>backend.composio.dev]-- D --> G[Composio exchanges code for token]- F --> G-- G --> H[Connection established]-- style E fill:#e1f5fe- style F fill:#e1f5fe- style C fill:#fff3e0-```--**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.--</Accordion>-</Accordions>-## What to read next<Cards>diff --git a/docs/content/docs/auth-configuration/meta.json b/docs/content/docs/auth-configuration/meta.jsonindex ad0ac4c3b..a84f4297b 100644--- a/docs/content/docs/auth-configuration/meta.json+++ b/docs/content/docs/auth-configuration/meta.json@@ -3,6 +3,7 @@"defaultOpen": false,"pages": ["custom-auth-configs",+ "white-labeling","programmatic-auth-configs","custom-auth-params","connected-accounts"diff --git a/docs/content/docs/auth-configuration/white-labeling.mdx b/docs/content/docs/auth-configuration/white-labeling.mdxnew file mode 100644index 000000000..566ce16e7--- /dev/null+++ b/docs/content/docs/auth-configuration/white-labeling.mdx@@ -0,0 +1,223 @@+---+title: White-labeling+description: Remove Composio branding from your auth flows+keywords: [branding, own oauth, custom redirect, white label]+llmGuardrails: "direct-execution"+---++<Callout type="info">+If you're building an agent with sessions, see [White-labeling authentication](/docs/white-labeling-authentication) instead.+</Callout>++There are three places where Composio branding shows up during authentication:++| Where | What users see | How to fix |+|-------|---------------|------------|+| [**Connect Link page**](#customizing-the-connect-link) | Composio logo and name on the hosted auth page | Change logo + app title in dashboard |+| [**OAuth consent screen**](#using-your-own-oauth-apps) | "Composio wants to access your account" on Google, GitHub, etc. | Use your own OAuth app |+| [**Browser address bar**](#custom-redirect-domain) | `backend.composio.dev` flashes during OAuth redirect | Proxy the redirect through your domain |++## Customizing the Connect Link++The Connect Link is the hosted page your users see when connecting their accounts. By default it shows Composio branding.++<Video src="/videos/authscreen.mp4" autoPlay />++To replace it with your own branding:++1. Go to **Project Settings** → [**Auth Screen**](https://platform.composio.dev?next_page=/settings/auth-screen)+2. Upload your **Logo** and set your **App Title**++This applies to all Connect Link flows across all toolkits. Each project has one logo and app title, so if you need different branding per product, use separate projects.++<Callout>+Customizing the Connect Link only changes the Composio-hosted page. For OAuth toolkits like Gmail, Google Sheets, GitHub, and Slack, users still see a consent screen saying "Composio wants to access your account." To change that, and to remove the "Secured by Composio" badge, set up your own OAuth app as described [below](#using-your-own-oauth-apps).+</Callout>++<Callout type="warn" title="Troubleshooting">+- **"Secured by Composio" badge won't go away:** This badge is removed when you use your own OAuth app. See [Using your own OAuth apps](#using-your-own-oauth-apps).+- **Logo doesn't appear after uploading:** Clear browser cache or try incognito.+- **Upload fails with "failed to fetch":** Retry or use a smaller image.+</Callout>++## Using your own OAuth apps++OAuth toolkits like Google and GitHub show a consent screen that says which app is requesting access. By default this reads "Composio wants to connect to your account." To show your app name instead, register your own OAuth app and tell Composio to use it. This is done by creating a [custom auth config](/docs/auth-configuration/custom-auth-configs) with your own credentials. See [when to use your own OAuth apps](#when-to-use-your-own-oauth-apps).++<Callout type="info" title="You don't need this for every toolkit">+Only white-label toolkits where users see a consent screen (Google, GitHub, Slack, etc.). Toolkits that use API keys don't show consent screens, so there's nothing to white-label. You can mix and match freely.+</Callout>++<Steps>+<Step>+<StepTitle>Create an OAuth app in the toolkit's developer portal</StepTitle>++Register a new OAuth app with the toolkit. Set the callback URL to:++```+https://backend.composio.dev/api/v3/toolkits/auth/callback+```++You'll get a **Client ID** and **Client Secret**.++Step-by-step guides: [Google](https://composio.dev/auth/googleapps) | [Slack](https://composio.dev/auth/slack) | [HubSpot](https://composio.dev/auth/hubspot) | [All toolkits](https://composio.dev/auth)+</Step>++<Step>+<StepTitle>Create an auth config in Composio</StepTitle>++In the [Composio dashboard](https://platform.composio.dev):++1. Go to **Authentication management** → **Create Auth Config**+2. Select the toolkit (e.g., GitHub)+3. Choose **OAuth2** scheme+4. Toggle on **Use your own developer credentials**+5. Enter your **Client ID** and **Client Secret**+6. Click **Create**++Copy the auth config ID (e.g., `ac_1234abcd`).++</Step>++<Step>+<StepTitle>Pass the auth config ID when initiating a connection</StepTitle>++Use your custom auth config ID for white-labeled toolkits. For everything else, use a Composio-managed auth config ID:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+from composio import Composio++composio = Composio(api_key="your_api_key")++# White-labeled: uses your OAuth app+github_conn = composio.connected_accounts.initiate(+ user_id="user_123",+ auth_config_id="ac_your_github_config",+)++# Composio-managed: uses Composio's default OAuth app+gmail_conn = composio.connected_accounts.initiate(+ user_id="user_123",+ auth_config_id="ac_composio_gmail_config",+)+```+</Tab>+<Tab value="TypeScript">+```typescript+import { Composio } from '@composio/core';+const composio = new Composio({ apiKey: 'your_api_key' });+// ---cut---+// White-labeled: uses your OAuth app+const githubConn = await composio.connectedAccounts.initiate(+ "user_123",+ "ac_your_github_config",+);++// Composio-managed: uses Composio's default OAuth app+const gmailConn = await composio.connectedAccounts.initiate(+ "user_123",+ "ac_composio_gmail_config",+);+```+</Tab>+</Tabs>++Now when users connect GitHub, they'll see your app name on the consent screen. For Gmail, Composio's default app handles it.+</Step>+</Steps>++### When to use your own OAuth apps++- **Production apps** where end users see consent screens. They should see your brand, not Composio's.+- **Enterprise customers** who require your branding end-to-end.+- **Toolkits where you need custom scopes** beyond what Composio's default app provides.++For development and testing, Composio's managed auth works fine. No OAuth app setup required.++## Custom redirect domain++During OAuth, the browser briefly redirects through `backend.composio.dev` so Composio can capture the auth token. Some toolkits also display this URL on the consent screen.++If you need to hide Composio's domain, you can proxy the redirect through your own domain instead.++<Steps>+<Step>+<StepTitle>Set the redirect URI to your domain</StepTitle>++In your OAuth app's settings, set the authorized redirect URI to your own endpoint:++```+https://yourdomain.com/api/composio-redirect+```+</Step>++<Step>+<StepTitle>Create a proxy endpoint</StepTitle>++This endpoint receives the OAuth callback and immediately 302-redirects it to Composio:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+from fastapi import FastAPI, Request+from fastapi.responses import RedirectResponse++app = FastAPI()+[email protected]("/api/composio-redirect")+def composio_redirect(request: Request):+ composio_url = "https://backend.composio.dev/api/v3/toolkits/auth/callback"+ return RedirectResponse(url=f"{composio_url}?{request.url.query}")+```+</Tab>+<Tab value="TypeScript">+```typescript+// pages/api/composio-redirect.ts (Next.js)+import type { NextApiRequest, NextApiResponse } from "next";++export default function handler(req: NextApiRequest, res: NextApiResponse) {+ const composioUrl = "https://backend.composio.dev/api/v3/toolkits/auth/callback";+ const params = new URLSearchParams(req.query as Record<string, string>);+ res.redirect(302, `${composioUrl}?${params.toString()}`);+}+```+</Tab>+</Tabs>++<Callout type="warn">+Your endpoint must return a **302 redirect**. Do not follow the redirect server-side or make a fetch call to Composio. The user's browser needs to be redirected so the OAuth flow completes correctly.+</Callout>+</Step>++<Step>+<StepTitle>Update your auth config</StepTitle>++In the Composio dashboard, update your auth config to use your custom redirect URI.++<Figure src="/images/custom-redirect-uri.png" alt="Auth Config Settings" caption="Setting the custom redirect URI in your auth config" size="sm" />+</Step>+</Steps>++Here's how the redirect flow works. Your proxy just forwards the browser redirect to Composio. It never touches the authorization code or token.++```mermaid+flowchart TD+ A[Your App] -->|User connects| B["OAuth toolkit (e.g. Google, GitHub)"]+ B -->|Redirects user| C[yourdomain.com]+ C -->|Forwards redirect| D[backend.composio.dev]+ D -.->|Redirects back| A+```++<Callout type="info">+For FAQs and setup guides for individual toolkits, browse the [toolkits page](/toolkits).+</Callout>++## What to read next++<Cards>+ <Card icon={<Database />} title="Connected accounts" href="/docs/auth-configuration/connected-accounts" description="Manage and monitor user connections to toolkits" />+ <Card icon={<Wrench />} title="Custom auth configs" href="/docs/auth-configuration/custom-auth-configs" description="Customize auth configs with your own OAuth apps" />+ <Card icon={<Key />} title="Authenticating tools" href="/docs/tools-direct/authenticating-tools" description="Create auth configs and connect user accounts" />+</Cards>diff --git a/docs/content/docs/tools-direct/authenticating-tools.mdx b/docs/content/docs/tools-direct/authenticating-tools.mdxindex 959eb6811..052700164 100644--- a/docs/content/docs/tools-direct/authenticating-tools.mdx+++ b/docs/content/docs/tools-direct/authenticating-tools.mdx@@ -54,7 +54,7 @@ Depending on your authentication method, you may need to configure scopes:You must provide your own credentials regardless of environment.<Callout type="info">-Want to remove Composio branding from OAuth screens? See [Custom Auth Configs](/docs/auth-configuration/custom-auth-configs#white-labeling-the-oauth-consent-screen) for white-labeling options.+Want to remove Composio branding from OAuth screens? See [White-labeling](/docs/auth-configuration/white-labeling) for details.</Callout></Step>@@ -82,7 +82,7 @@ You should create multiple auth configs for the same toolkit when you need:<Card title="Programmatic creation" href="/docs/auth-configuration/programmatic-auth-configs">For managing auth configs across multiple projects, you can create them programmatically via the API</Card>- <Card title="Production white-labeling" href="/docs/auth-configuration/custom-auth-configs#white-labeling-the-oauth-consent-screen">+ <Card title="Production white-labeling" href="/docs/auth-configuration/white-labeling">Remove Composio branding from OAuth screens for a fully white-labeled authentication experience</Card></Cards>@@ -156,16 +156,11 @@ console.log(`Visit: ${redirectUrl} to authenticate your account`);#### Customizing Connect Link-By default, users will see a Composio-branded authentication experience when connecting their accounts. To customize this interface with your application's branding:+You can customize the Connect Link with your logo and app title, or fully white-label OAuth consent screens with your own developer apps.-1. Navigate to your Project Settings and select [Auth Screen](https://platform.composio.dev?next_page=/settings/auth-screen)-2. Configure your **Logo** and **App Title**--These settings will apply to all authentication flows using Connect Link, providing a white-labeled experience that maintains your brand identity throughout the authentication process.--<Callout>-For complete white-labeling including OAuth consent screens (removing Composio's domain), see [Custom Auth Configs - White-labeling](/docs/auth-configuration/custom-auth-configs#white-labeling-the-oauth-consent-screen).-</Callout>+<Cards>+ <Card icon={<Palette />} title="White-labeling" href="/docs/auth-configuration/white-labeling" description="Remove Composio branding from OAuth screens and auth flows" />+</Cards>#### Redirecting users after authentication@@ -527,5 +522,5 @@ Only connections with **ACTIVE** status can be used to execute tools. If a conne<Cards><Card icon={<Play />} title="Executing tools" href="/docs/tools-direct/executing-tools" description="Run tools with providers, agentic frameworks, or direct execution" /><Card icon={<Database />} title="Connected accounts" href="/docs/auth-configuration/connected-accounts" description="Manage and monitor user connections to toolkits" />- <Card icon={<Palette />} title="Custom auth configs" href="/docs/auth-configuration/custom-auth-configs" description="Use your own OAuth apps for white-labeled authentication" />+ <Card icon={<Palette />} title="White-labeling" href="/docs/auth-configuration/white-labeling" description="Remove Composio branding from OAuth screens and auth flows" /></Cards>diff --git a/docs/content/docs/using-custom-auth-configuration.mdx b/docs/content/docs/using-custom-auth-configuration.mdxindex 0d0acce01..56921ff2c 100644--- a/docs/content/docs/using-custom-auth-configuration.mdx+++ b/docs/content/docs/using-custom-auth-configuration.mdx@@ -4,7 +4,13 @@ description: Set up auth configs for toolkits without Composio managed authentickeywords: [custom credentials, no managed auth]----Some toolkits don't have Composio managed authentication and require you to provide your own credentials. When sessions try to use these toolkits, an error will be thrown asking you to create an auth config.+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](/docs/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)<Steps><Step>diff --git a/docs/content/docs/white-labeling-authentication.mdx b/docs/content/docs/white-labeling-authentication.mdxindex adc81b1a3..845321121 100644--- a/docs/content/docs/white-labeling-authentication.mdx+++ b/docs/content/docs/white-labeling-authentication.mdx@@ -1,51 +1,83 @@---title: White-labeling authentication-description: Use your own OAuth apps and branded auth screens-keywords: [branding, own oauth, custom redirect]+description: Remove Composio branding from your auth flows+keywords: [branding, own oauth, custom redirect, white label]----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".+There are three places where Composio branding shows up during authentication:-By default, OAuth screens show Composio's branding. With white-labeling, they'll see your app name and logo.+| Where | What users see | How to fix |+|-------|---------------|------------|+| [**Connect Link page**](#customizing-the-connect-link) | Composio logo and name on the hosted auth page | Change logo + app title in dashboard |+| [**OAuth consent screen**](#using-your-own-oauth-apps) | "Composio wants to access your account" on Google, GitHub, etc. | Use your own OAuth app |+| [**Browser address bar**](#custom-redirect-domain) | `backend.composio.dev` flashes during OAuth redirect | Proxy the redirect through your domain |++## Customizing the Connect Link++The Connect Link is the hosted page your users see when connecting their accounts. By default it shows Composio branding.++<Video src="/videos/authscreen.mp4" autoPlay />++To replace it with your own branding:++1. Go to **Project Settings** → [**Auth Screen**](https://platform.composio.dev?next_page=/settings/auth-screen)+2. Upload your **Logo** and set your **App Title**++This applies to all Connect Link flows across all toolkits, for both [in-chat](/docs/authenticating-users/in-chat-authentication) and [manual](/docs/authenticating-users/manually-authenticating) authentication. Each project has one logo and app title, so if you need different branding per product, use separate projects.++<Callout>+Customizing the Connect Link only changes the Composio-hosted page. For OAuth toolkits like Gmail, Google Sheets, GitHub, and Slack, users still see a consent screen saying "Composio wants to access your account." To change that, and to remove the "Secured by Composio" badge, set up your own OAuth app as described [below](#using-your-own-oauth-apps).+</Callout>++<Callout type="warn" title="Troubleshooting">+- **"Secured by Composio" badge won't go away:** This badge is removed when you use your own OAuth app. See [Using your own OAuth apps](#using-your-own-oauth-apps).+- **Logo doesn't appear after uploading:** Clear browser cache or try incognito.+- **Upload fails with "failed to fetch":** Retry or use a smaller image.+</Callout>++## Using your own OAuth apps++OAuth toolkits like Google and GitHub show a consent screen that says which app is requesting access. By default this reads "Composio wants to connect to your account." To show your app name instead, register your own OAuth app and tell Composio to use it. This is done by creating a [custom auth config](/docs/using-custom-auth-configuration) with your own credentials. See [when to use your own OAuth apps](#when-to-use-your-own-oauth-apps).++<Callout type="info" title="You don't need this for every toolkit">+Only white-label toolkits where users see a consent screen (Google, GitHub, Slack, etc.). Toolkits that use API keys don't show consent screens, so there's nothing to white-label. You can mix and match freely.+</Callout><Steps><Step>-<StepTitle>Create an OAuth app</StepTitle>+<StepTitle>Create an OAuth app in the toolkit's developer portal</StepTitle>-Create a developer app in the toolkit's developer portal. You'll need the client ID and client secret. Set the callback URL to:+Register a new OAuth app with the toolkit. Set the callback URL to:```https://backend.composio.dev/api/v3/toolkits/auth/callback```-<Callout type="info">-For step-by-step guides on creating OAuth apps for some toolkits, see [composio.dev/auth](https://composio.dev/auth).-</Callout>+You'll get a **Client ID** and **Client Secret**.++Step-by-step guides: [Google](https://composio.dev/auth/googleapps) | [Slack](https://composio.dev/auth/slack) | [HubSpot](https://composio.dev/auth/hubspot) | [All toolkits](https://composio.dev/auth)</Step><Step>-<StepTitle>Create auth config</StepTitle>+<StepTitle>Create an auth config in Composio</StepTitle>-Create an auth config in the [Composio dashboard](https://platform.composio.dev):+In the [Composio dashboard](https://platform.composio.dev):1. Go to **Authentication management** → **Create Auth Config**2. Select the toolkit (e.g., GitHub)3. Choose **OAuth2** scheme-4. Enter your **Client ID** and **Client Secret**-5. Select the scopes you need+4. Toggle on **Use your own developer credentials**+5. Enter your **Client ID** and **Client Secret**6. Click **Create**Copy the auth config ID (e.g., `ac_1234abcd`).-<Callout type="info">-For detailed instructions with screenshots, see [Custom auth configs](/docs/auth-configuration/custom-auth-configs).-</Callout></Step><Step>-<StepTitle>Use in your session</StepTitle>+<StepTitle>Pass the auth config ID in your session</StepTitle>-Pass your auth config ID in the session:+Specify which toolkits should use your custom auth config. Any toolkit you don't specify here will use Composio's managed auth automatically:<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">@@ -53,7 +85,9 @@ Pass your auth config ID in the session:session = composio.create(user_id="user_123",auth_configs={- "github": "ac_your_github_config"+ "github": "ac_your_github_config",+ "slack": "ac_your_slack_config",+ # gmail, linear, etc. use Composio managed auth automatically},)```@@ -66,61 +100,47 @@ const composio = new Composio({ apiKey: 'your_api_key' });const session = await composio.create("user_123", {authConfigs: {github: "ac_your_github_config",+ slack: "ac_your_slack_config",+ // gmail, linear, etc. use Composio managed auth automatically},});```</Tab></Tabs>-When users connect GitHub, they'll see your OAuth app's name and logo on the consent screen.+Now when users connect GitHub or Slack, they'll see your app name on the consent screen. For Gmail and everything else, Composio's default app handles it.</Step></Steps>-## Mixing custom and Composio-managed auth+### When to use your own OAuth apps-You can white-label some toolkits while using Composio's managed credentials for others:+- **Production apps** where end users see consent screens. They should see your brand, not Composio's.+- **Enterprise customers** who require your branding end-to-end.+- **Toolkits where you need custom scopes** beyond what Composio's default app provides.-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>-<Tab value="Python">-```python-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- },-)-```-</Tab>-<Tab value="TypeScript">-```typescript-import { Composio } from '@composio/core';-const composio = new Composio({ apiKey: 'your_api_key' });-// ---cut----const session = await composio.create("user_123", {- authConfigs: {- github: "ac_your_github_config",- slack: "ac_your_slack_config",- // gmail, linear, etc. use Composio managed auth- },-});-```-</Tab>-</Tabs>+For development and testing, Composio's managed auth works fine. No OAuth app setup required.## 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.+During OAuth, the browser briefly redirects through `backend.composio.dev` so Composio can capture the auth token. Some toolkits also display this URL on the consent screen.++If you need to hide Composio's domain, you can proxy the redirect through your own domain instead.++<Steps>+<Step>+<StepTitle>Set the redirect URI to your domain</StepTitle>-If you need to hide this URL (for enterprise compliance or complete white-labeling), you can proxy the redirect through your own domain:+In your OAuth app's settings, set the authorized redirect URI to your own endpoint:-1. Set your OAuth app's redirect URI to your domain:```https://yourdomain.com/api/composio-redirect```+</Step>-2. Create an endpoint that forwards the OAuth callback to Composio:+<Step>+<StepTitle>Create a proxy endpoint</StepTitle>++This endpoint receives the OAuth callback and immediately 302-redirects it to Composio:<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">@@ -132,7 +152,6 @@ app = FastAPI()@app.get("/api/composio-redirect")def composio_redirect(request: Request):- # Forward all OAuth parameters to Composiocomposio_url = "https://backend.composio.dev/api/v3/toolkits/auth/callback"return RedirectResponse(url=f"{composio_url}?{request.url.query}")```@@ -143,7 +162,6 @@ def composio_redirect(request: Request):import type { NextApiRequest, NextApiResponse } from "next";export default function handler(req: NextApiRequest, res: NextApiResponse) {- // Forward all OAuth parameters to Composioconst composioUrl = "https://backend.composio.dev/api/v3/toolkits/auth/callback";const params = new URLSearchParams(req.query as Record<string, string>);res.redirect(302, `${composioUrl}?${params.toString()}`);@@ -152,14 +170,37 @@ export default function handler(req: NextApiRequest, res: NextApiResponse) {</Tab></Tabs>-3. Update your auth config in the Composio dashboard to use your custom redirect URI.+<Callout type="warn">+Your endpoint must return a **302 redirect**. Do not follow the redirect server-side or make a fetch call to Composio. The user's browser needs to be redirected so the OAuth flow completes correctly.+</Callout>+</Step>++<Step>+<StepTitle>Update your auth config</StepTitle>++In the Composio dashboard, update your auth config to use your custom redirect URI.-This makes the OAuth flow go through your domain first, then to Composio for token storage.+<Figure src="/images/custom-redirect-uri.png" alt="Auth Config Settings" caption="Setting the custom redirect URI in your auth config" size="sm" />+</Step>+</Steps>++Here's how the redirect flow works. Your proxy just forwards the browser redirect to Composio. It never touches the authorization code or token.++```mermaid+flowchart TD+ A[Your App] -->|User connects| B["OAuth toolkit (e.g. Google, GitHub)"]+ B -->|Redirects user| C[yourdomain.com]+ C -->|Forwards redirect| D[backend.composio.dev]+ D -.->|Redirects back| A+```++<Callout type="info">+For FAQs and setup guides for individual toolkits, browse the [toolkits page](/toolkits).+</Callout>## What to read next<Cards><Card icon={<Key />} title="Using custom auth configuration" href="/docs/using-custom-auth-configuration" description="Set up auth configs for toolkits that don't have Composio managed authentication" /><Card icon={<Key />} title="Authentication overview" href="/docs/authentication" description="Connect Links, OAuth, API keys, and how Composio manages auth" />- <Card icon={<Wrench />} title="Configuring sessions" href="/docs/configuring-sessions" description="Pass auth configs, connected accounts, and toolkit restrictions to sessions" /></Cards>diff --git a/docs/content/toolkits/faq/gmail.md b/docs/content/toolkits/faq/gmail.mdindex bf84b4b7d..d336bedf1 100644--- a/docs/content/toolkits/faq/gmail.md+++ b/docs/content/toolkits/faq/gmail.md@@ -18,7 +18,7 @@ The requested scopes are invalid or incorrectly formatted in the authorization U## Why does the OAuth consent screen show "Composio" instead of my app?-By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling the OAuth consent screen](/docs/auth-configuration/custom-auth-configs#white-labeling-the-oauth-consent-screen).+By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).## Why am I getting 401 errors on tool calls?diff --git a/docs/content/toolkits/faq/google_classroom.md b/docs/content/toolkits/faq/google_classroom.mdindex 62f09ceef..cd7d75c62 100644--- a/docs/content/toolkits/faq/google_classroom.md+++ b/docs/content/toolkits/faq/google_classroom.md@@ -18,7 +18,7 @@ The requested scopes are invalid or incorrectly formatted in the authorization U## Why does the OAuth consent screen show "Composio" instead of my app?-By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling the OAuth consent screen](/docs/auth-configuration/custom-auth-configs#white-labeling-the-oauth-consent-screen).+By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).## Why am I getting 401 errors on tool calls?diff --git a/docs/content/toolkits/faq/google_maps.md b/docs/content/toolkits/faq/google_maps.mdindex 255e3c331..e0dc28432 100644--- a/docs/content/toolkits/faq/google_maps.md+++ b/docs/content/toolkits/faq/google_maps.md@@ -18,7 +18,7 @@ The requested scopes are invalid or incorrectly formatted in the authorization U## Why does the OAuth consent screen show "Composio" instead of my app?-By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling the OAuth consent screen](/docs/auth-configuration/custom-auth-configs#white-labeling-the-oauth-consent-screen).+By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).## Why am I getting 401 errors on tool calls?diff --git a/docs/content/toolkits/faq/googlecalendar.md b/docs/content/toolkits/faq/googlecalendar.mdindex c2d7bb744..c96db4bf8 100644--- a/docs/content/toolkits/faq/googlecalendar.md+++ b/docs/content/toolkits/faq/googlecalendar.md@@ -18,7 +18,7 @@ The requested scopes are invalid or incorrectly formatted in the authorization U## Why does the OAuth consent screen show "Composio" instead of my app?-By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling the OAuth consent screen](/docs/auth-configuration/custom-auth-configs#white-labeling-the-oauth-consent-screen).+By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).## Why am I getting 401 errors on tool calls?diff --git a/docs/content/toolkits/faq/googledocs.md b/docs/content/toolkits/faq/googledocs.mdindex 3fa7d48b4..ecd4f0204 100644--- a/docs/content/toolkits/faq/googledocs.md+++ b/docs/content/toolkits/faq/googledocs.md@@ -18,7 +18,7 @@ The requested scopes are invalid or incorrectly formatted in the authorization U## Why does the OAuth consent screen show "Composio" instead of my app?-By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling the OAuth consent screen](/docs/auth-configuration/custom-auth-configs#white-labeling-the-oauth-consent-screen).+By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).## Why am I getting 401 errors on tool calls?diff --git a/docs/content/toolkits/faq/googledrive.md b/docs/content/toolkits/faq/googledrive.mdindex 5e60c970f..fed66729e 100644--- a/docs/content/toolkits/faq/googledrive.md+++ b/docs/content/toolkits/faq/googledrive.md@@ -18,7 +18,7 @@ The requested scopes are invalid or incorrectly formatted in the authorization U## Why does the OAuth consent screen show "Composio" instead of my app?-By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling the OAuth consent screen](/docs/auth-configuration/custom-auth-configs#white-labeling-the-oauth-consent-screen).+By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).## Why am I getting 401 errors on tool calls?diff --git a/docs/content/toolkits/faq/googlemeet.md b/docs/content/toolkits/faq/googlemeet.mdindex e2903044e..60b86ffe7 100644--- a/docs/content/toolkits/faq/googlemeet.md+++ b/docs/content/toolkits/faq/googlemeet.md@@ -18,7 +18,7 @@ The requested scopes are invalid or incorrectly formatted in the authorization U## Why does the OAuth consent screen show "Composio" instead of my app?-By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling the OAuth consent screen](/docs/auth-configuration/custom-auth-configs#white-labeling-the-oauth-consent-screen).+By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).## Why am I getting 401 errors on tool calls?diff --git a/docs/content/toolkits/faq/googlesheets.md b/docs/content/toolkits/faq/googlesheets.mdindex 57887eee0..a94462fb3 100644--- a/docs/content/toolkits/faq/googlesheets.md+++ b/docs/content/toolkits/faq/googlesheets.md@@ -18,7 +18,7 @@ The requested scopes are invalid or incorrectly formatted in the authorization U## Why does the OAuth consent screen show "Composio" instead of my app?-By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling the OAuth consent screen](/docs/auth-configuration/custom-auth-configs#white-labeling-the-oauth-consent-screen).+By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).## Why am I getting 401 errors on tool calls?diff --git a/docs/content/toolkits/faq/googleslides.md b/docs/content/toolkits/faq/googleslides.mdindex 08b887372..da72efd2a 100644--- a/docs/content/toolkits/faq/googleslides.md+++ b/docs/content/toolkits/faq/googleslides.md@@ -18,7 +18,7 @@ The requested scopes are invalid or incorrectly formatted in the authorization U## Why does the OAuth consent screen show "Composio" instead of my app?-By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling the OAuth consent screen](/docs/auth-configuration/custom-auth-configs#white-labeling-the-oauth-consent-screen).+By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).## Why am I getting 401 errors on tool calls?diff --git a/docs/content/toolkits/faq/googlesuper.md b/docs/content/toolkits/faq/googlesuper.mdindex 78a2889fb..fa5a48e69 100644--- a/docs/content/toolkits/faq/googlesuper.md+++ b/docs/content/toolkits/faq/googlesuper.md@@ -18,6 +18,6 @@ The requested scopes are invalid or incorrectly formatted in the authorization U## Why does the OAuth consent screen show "Composio" instead of my app?-By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling the OAuth consent screen](/docs/auth-configuration/custom-auth-configs#white-labeling-the-oauth-consent-screen).+By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).---diff --git a/docs/content/toolkits/faq/googletasks.md b/docs/content/toolkits/faq/googletasks.mdindex 7154ff266..7663f4a4b 100644--- a/docs/content/toolkits/faq/googletasks.md+++ b/docs/content/toolkits/faq/googletasks.md@@ -18,7 +18,7 @@ The requested scopes are invalid or incorrectly formatted in the authorization U## Why does the OAuth consent screen show "Composio" instead of my app?-By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling the OAuth consent screen](/docs/auth-configuration/custom-auth-configs#white-labeling-the-oauth-consent-screen).+By default, the consent screen uses Composio's OAuth app. To show your own app name and logo, create your own OAuth app and set a custom redirect URL. See [White-labeling authentication](/docs/white-labeling-authentication#using-your-own-oauth-apps).## Why am I getting 401 errors on tool calls?diff --git a/docs/public/videos/authscreen.mp4 b/docs/public/videos/authscreen.mp4new file mode 100644index 000000000..c94ee559dBinary files /dev/null and b/docs/public/videos/authscreen.mp4 differ