@devries-cameron20 / composio-1 / commits / 301f305a7
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

white labeling(to edit)

Sushmithamallesh committed Dec 3, 2025 at 16:38 UTC 301f305a746eeb9760808b4641167bcc29726b88
2 files changed +131 -2
fern/assets/images/oauth-composio-branding.png
Binary files /dev/null and b/fern/assets/images/oauth-composio-branding.png differ
fern/pages/src/tool-router/white-labeling-authentication.mdx
+131 -2
@@ -1,7 +1,136 @@
1 ---
2 -title: White-labeling Authentication
2 +title: White-labeling authentication
3 image: "https://og.composio.dev/api/og?title=White-labeling%20Authentication"
4 description: "Use your own OAuth apps and branded auth screens"
5 -keywords: "tool router"
5 +keywords: "tool router, white-label, oauth, custom auth, branding"
6 ---
7
8 +By default, users see Composio's branding on OAuth consent screens:
9 +
10 +<Frame>
11 + <img src="../../../assets/images/oauth-composio-branding.png" />
12 +</Frame>
13 +
14 +White-labeling lets you show your own app name and logo instead.
15 +
16 +<Steps>
17 +<Step title="Create an OAuth app">
18 +Create a developer app in the toolkit's developer portal. You'll need the client ID, client secret, and set the callback URL to:
19 +
20 +```
21 +https://backend.composio.dev/api/v3/toolkits/auth/callback
22 +```
23 +
24 +<Tip>
25 +For step-by-step guides on creating OAuth apps for some toolkits, see [composio.dev/auth](https://composio.dev/auth).
26 +</Tip>
27 +</Step>
28 +
29 +<Step title="Create auth config">
30 +Create an auth config in the [Composio dashboard](https://app.composio.dev):
31 +
32 +1. Go to **Authentication management** → **Create Auth Config**
33 +2. Select the toolkit (e.g., GitHub)
34 +3. Choose **OAuth2** scheme
35 +4. Enter your **Client ID** and **Client Secret**
36 +5. Select the scopes you need
37 +6. Click **Create**
38 +
39 +Copy the auth config ID (e.g., `ac_1234abcd`).
40 +
41 +<Tip>
42 +For detailed instructions with screenshots, see [Custom auth configs](/docs/authentication/custom-auth-configs).
43 +</Tip>
44 +</Step>
45 +
46 +<Step title="Use in Tool Router">
47 +Pass your auth config ID in the session:
48 +
49 +<CodeGroup>
50 +```python
51 +session = await composio.create_session(
52 + user="pg-user-550e8400-e29b-41d4",
53 + auth_configs={
54 + "github": "ac_your_github_config"
55 + },
56 +)
57 +```
58 +```typescript
59 +const session = await composio.createSession({
60 + user: "pg-user-550e8400-e29b-41d4",
61 + authConfigs: {
62 + github: "ac_your_github_config",
63 + },
64 +});
65 +```
66 +</CodeGroup>
67 +
68 +When users connect GitHub, they'll see your OAuth app's name and logo on the consent screen.
69 +</Step>
70 +</Steps>
71 +
72 +## Mix white-labeled and Composio managed
73 +
74 +You can white-label some toolkits while using Composio's default credentials for others:
75 +
76 +<CodeGroup>
77 +```python
78 +session = await composio.create_session(
79 + user="pg-user-550e8400-e29b-41d4",
80 + auth_configs={
81 + "github": "ac_your_github_config",
82 + "slack": "ac_your_slack_config",
83 + # gmail, linear, etc. use Composio managed auth
84 + },
85 +)
86 +```
87 +```typescript
88 +const session = await composio.createSession({
89 + user: "pg-user-550e8400-e29b-41d4",
90 + authConfigs: {
91 + github: "ac_your_github_config",
92 + slack: "ac_your_slack_config",
93 + // gmail, linear, etc. use Composio managed auth
94 + },
95 +});
96 +```
97 +</CodeGroup>
98 +
99 +## Custom redirect domain
100 +
101 +By default, users see `backend.composio.dev` in the OAuth flow. To show your own domain:
102 +
103 +1. Set your OAuth app's redirect URI to your domain:
104 +```
105 +https://yourdomain.com/api/composio-redirect
106 +```
107 +
108 +2. Create an endpoint that forwards to Composio:
109 +
110 +<CodeGroup>
111 +```python
112 +from fastapi import FastAPI, Request
113 +from fastapi.responses import RedirectResponse
114 +
115 +app = FastAPI()
116 +
117 +@app.get("/api/composio-redirect")
118 +def composio_redirect(request: Request):
119 + composio_url = "https://backend.composio.dev/api/v3/toolkits/auth/callback"
120 + query_string = str(request.query_params)
121 + return RedirectResponse(url=f"{composio_url}?{query_string}")
122 +```
123 +```typescript
124 +// pages/api/composio-redirect.ts (Next.js)
125 +import type { NextApiRequest, NextApiResponse } from "next";
126 +
127 +export default function handler(req: NextApiRequest, res: NextApiResponse) {
128 + const composioUrl = "https://backend.composio.dev/api/v3/toolkits/auth/callback";
129 + const params = new URLSearchParams(req.query as Record<string, string>);
130 + res.redirect(302, `${composioUrl}?${params.toString()}`);
131 +}
132 +```
133 +</CodeGroup>
134 +
135 +3. Update your auth config in the dashboard to use your custom redirect URI.
136 +