Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: document app-owned OAuth flows and domain limits
Brendan O'Leary committed
Oct 21, 2026 at 04:11 UTC
d7a253606fc7f31448563a612a73c810d2628b8d
4 files changed
+216
-415
docs/components/white-label-flow.tsx
+9
-14
@@ -14,26 +14,21 @@ const NODES: {
14
},
15
{
16
label: 'yourdomain.com',
17
- sub: 'your proxy endpoint',
17
+ sub: 'receives code and state',
18
edge: 'redirects user',
19
accent: true,
20
},
21
{
22
label: 'backend.composio.dev',
23
- sub: 'captures the token',
24
- edge: 'forwards redirect',
23
+ sub: 'exchanges code for tokens',
24
+ edge: 'browser follows 302',
25
},
26
];
27
28
/**
29
- * WhiteLabelFlow — branded replacement for the OAuth redirect-proxy mermaid
30
- * diagram on the white-labeling pages.
31
- *
32
- * Shows the browser redirect hop through your own domain: the user connects,
33
- * the toolkit redirects to your proxy, your proxy forwards to Composio, and
34
- * Composio sends the user back to your app. Your domain is brand-accented
35
- * because it's the white-label point. The proxy never touches the token, only
36
- * the browser redirect. Server component, light/dark via fd-* tokens.
29
+ * Browser hops for a GET-query OAuth2 callback forwarded through your domain.
30
+ * Your endpoint receives the authorization code and state, then redirects the
31
+ * browser to Composio for token exchange. It must not log the callback query.
32
*/
33
export function WhiteLabelFlow() {
34
return (
@@ -99,9 +94,9 @@ export function WhiteLabelFlow() {
94
aria-hidden="true"
95
className="size-3 text-[var(--composio-brand)]"
96
/>
102
- Composio redirects the user back to{' '}
103
- <code className="text-fd-foreground/70">your app</code>. Your proxy
104
- never sees the token
97
+ The browser still visits Composio before returning to{' '}
98
+ <code className="text-fd-foreground/70">your app</code>. Your endpoint
99
+ receives code and state; do not log them.
100
</div>
101
</div>
102
);
docs/content/docs/auth-configuration/white-labeling.mdx
+13
-293
@@ -1,326 +1,46 @@
1
---
2
title: White-labeling (direct execution)
3
-description: Remove Composio branding from your auth flows
3
+description: Choose branded hosted authentication or an app-owned UI with custom OAuth apps
4
keywords: [branding, own oauth, custom redirect, white label]
5
llmGuardrails: "direct-execution"
6
legacy: true
7
---
8
9
-<Callout type="info">
10
-If you're building an agent with sessions, see [White-labeling authentication](/docs/authentication/white-labeling-authentication) instead.
11
-</Callout>
12
-
13
-There are four places where Composio branding shows up during authentication:
14
-
15
-| Where | What users see | How to fix |
16
-|-------|---------------|------------|
17
-| [**Connect Link page**](#customizing-the-connect-link) | Composio logo, name, and styling on the hosted auth page | Set your logo, app title, and theme in the dashboard |
18
-| [**OAuth consent screen**](#using-your-own-oauth-apps) | "Composio wants to access your account" on Google, GitHub, etc. | Use your own OAuth app |
19
-| [**Outgoing redirect**](#sending-users-directly-to-the-oauth-provider) | `backend.composio.dev` in browser before reaching OAuth provider | Use `long_redirect_url` option |
20
-| [**Return redirect**](#routing-the-callback-through-your-domain) | `backend.composio.dev` flashes when OAuth provider redirects back | Proxy the redirect through your domain |
9
+The [White-labeling authentication guide](/docs/authentication/white-labeling-authentication) covers both hosted Connect Link branding and app-owned connection UI. The same OAuth app and callback rules apply whether you use direct tool execution or sessions.
10
11
## Customizing the Connect Link
12
24
-The Connect Link is the hosted page your users see when connecting their accounts. By default it shows Composio branding on a neutral light theme. You can swap in your logo and name, then restyle the whole page to match your product.
25
-
26
-Everything here lives in **Project Settings** → [**White Labeling**](https://dashboard.composio.dev/~/project/settings/auth-screen?utm_source=docs&utm_medium=content&utm_campaign=docs-auth-configuration-white-labeling). Changes apply to every Connect Link flow across all toolkits. Each project has one branding and one theme, so if you need a different look per product, use separate projects.
27
-
28
-### Logo and name
29
-
30
-1. Go to **Project Settings** → **White Labeling**, and open the **Branding** tab.
31
-2. Set your **App Title** and upload your **Logo** (a square JPEG or PNG, 256×256 to 1024×1024 pixels).
32
-
33
-The logo replaces the Composio mark at the top of the page, and the app title replaces "Composio" in the "...wants to connect to your account" heading.
34
-
35
-<Callout>
36
-This 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).
37
-</Callout>
38
-
39
-### Colors, fonts, and per-element styling
40
-
41
-Open the **Styling** tab to restyle the entire Connect Link page. A live preview sits beside the controls and updates as you edit, and you can preview each state of the flow with the **Welcome**, **Form**, **Success**, and **Error** tabs.
42
-
43
-<Figure src="/images/auth-screen-theme-editor.png" alt="The White Labeling editor with a live preview on the left and styling controls on the right" caption="Editing colors, fonts, and per-element styling with a live preview of the Connect Link" />
44
-
45
-Set the page-wide defaults first:
46
-
47
-- **Seed colours** for the page background, card, foreground text, and primary accent, plus secondary and tertiary accents for decorative touches.
48
-- **Typefaces**: a display font for headings and a body font, each chosen from a curated set. The default is ABC Diatype.
49
-- **Geometry**: corner radius and border width, which set the roundness and outline weight of cards, buttons, and inputs.
50
-
51
-For finer control, select any element in the preview to style just that element. Editable elements cover the page and card surfaces, the heading, body, and field labels, the primary and secondary buttons, the input, the error notice, links, and the logo. Depending on the element you can set its colour, background, border, corner radius, shadow, and text size, weight, letter spacing, and case.
52
-
53
-<Callout type="info" title="Contrast is enforced">
54
-Text has to stay legible against its background. The editor shows the contrast ratio for each text element and disables **Save Changes** until every element passes, so you can't ship an unreadable page by accident.
55
-</Callout>
56
-
57
-Prefer to work in code? Flip the **JSON** toggle to edit the theme as a single object you can paste, review, or generate. Your logo and app title stay in the **Branding** tab, since the logo has no JSON representation.
58
-
59
-### Language
13
+Use `composio.connectedAccounts.link(userId, authConfigId, { callbackUrl })` in TypeScript or `composio.connected_accounts.link(user_id=..., auth_config_id=..., callback_url=...)` in Python to start a hosted flow without a session. The [server-side cURL example](/docs/authentication/white-labeling-authentication#choose-your-connection-ui) shows the equivalent API request.
14
61
-The Connect Link shows English by default. To show it in your user's language, add a `locale` parameter to the Connect Link URL before you send it to the user. The Connect Link supports these languages:
62
-
63
-| Language | `locale` value |
64
-|----------|----------------|
65
-| English | `en` (default) |
66
-| Spanish | `es` |
67
-| Simplified Chinese | `zh-CN` |
68
-
69
-Use these values exactly as written. Any other value, including variants such as `es-MX` or `zh-cn`, shows English. The language stays the same for the whole flow, including the success or failure screen after the user returns from the OAuth provider.
70
-
71
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
72
-<Tab value="Python">
73
-```python
74
-from urllib.parse import urlencode
75
-
76
-connection_request = composio.connected_accounts.link(
77
- user_id="user_123",
78
- auth_config_id="ac_abc",
79
-)
80
-
81
-# Show the Connect Link in Spanish
82
-connect_url = f"{connection_request.redirect_url}?{urlencode({'locale': 'es'})}"
83
-```
84
-</Tab>
85
-<Tab value="TypeScript">
86
-```typescript
87
-import { Composio } from '@composio/core';
88
-const composio = new Composio({ apiKey: 'your_api_key' });
89
-// ---cut---
90
-const connectionRequest = await composio.connectedAccounts.link('user_123', 'ac_abc');
91
-
92
-if (connectionRequest.redirectUrl) {
93
- // Show the Connect Link in Spanish
94
- const connectUrl = new URL(connectionRequest.redirectUrl);
95
- connectUrl.searchParams.set("locale", "es");
96
- console.log(connectUrl.toString());
97
-}
98
-```
99
-</Tab>
100
-</Tabs>
101
-
102
-The `locale` parameter changes only the Connect Link's own text. Field names and help text on API key forms, error details from the provider, and the provider's own sign-in and consent screens keep their original language. If you pass `long_redirect_url`, users go straight to the OAuth provider and never see the Connect Link, so `locale` has no effect.
103
-
104
-<Callout type="warn" title="Troubleshooting">
105
-- **"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).
106
-- **Logo doesn't appear after uploading:** clear your browser cache or try incognito.
107
-- **Upload fails with "failed to fetch":** retry or use a smaller image.
108
-- **You see the Branding tab but no Styling tab:** theming is still rolling out. If it isn't enabled for your project yet, reach out. The logo and app title keep working in the meantime.
109
-</Callout>
15
+Set your project's logo, app title, theme, and language as described in [Customizing the Connect Link](/docs/authentication/white-labeling-authentication#customizing-the-connect-link). Branding changes the hosted page, not its `connect.composio.dev` domain or the provider's consent screen.
16
17
## Using your own OAuth apps
18
113
-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).
114
-
115
-<Callout type="info" title="You don't need this for every toolkit">
116
-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.
117
-</Callout>
118
-
119
-<Steps>
120
-<Step>
121
-<StepTitle>Create an OAuth app in the toolkit's developer portal</StepTitle>
122
-
123
-Register a new OAuth app with the toolkit. Set the callback URL to:
124
-
125
-```
126
-https://backend.composio.dev/api/v3/toolkits/auth/callback
127
-```
128
-
129
-You'll get a **Client ID** and **Client Secret**.
130
-
131
-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)
132
-</Step>
133
-
134
-<Step>
135
-<StepTitle>Create an auth config in Composio</StepTitle>
136
-
137
-In the [Composio dashboard](https://dashboard.composio.dev?utm_source=docs&utm_medium=content&utm_campaign=docs-auth-configuration-white-labeling):
138
-
139
-1. Go to **Authentication management** → **Create Auth Config**
140
-2. Select the toolkit (e.g., GitHub)
141
-3. Choose **OAuth2** scheme
142
-4. Toggle on **Use your own developer credentials**
143
-5. Enter your **Client ID** and **Client Secret**
144
-6. Set **Redirect URI** to the same callback URL you registered with the provider
145
-7. Click **Create**
146
-
147
-Copy the auth config ID (e.g., `ac_1234abcd`).
148
-
149
-</Step>
150
-
151
-<Step>
152
-<StepTitle>Pass the auth config ID when initiating a connection</StepTitle>
153
-
154
-Pass your custom auth config ID when initiating a connection:
155
-
156
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
157
-<Tab value="Python">
158
-```python
159
-from composio import Composio
160
-
161
-composio = Composio(api_key="your_api_key")
162
-
163
-# White-labeled: users see your brand on the consent screen
164
-github_conn = composio.connected_accounts.initiate(
165
- user_id="user_123",
166
- auth_config_id="ac_your_github_config",
167
-)
168
-print(f"Redirect to: {github_conn.redirect_url}")
169
-```
170
-</Tab>
171
-<Tab value="TypeScript">
172
-```typescript
173
-import { Composio } from '@composio/core';
174
-const composio = new Composio({ apiKey: 'your_api_key' });
175
-// ---cut---
176
-// White-labeled: users see your brand on the consent screen
177
-const githubConn = await composio.connectedAccounts.initiate(
178
- "user_123",
179
- "ac_your_github_config",
180
-);
181
-console.log("Redirect to:", githubConn.redirectUrl);
182
-```
183
-</Tab>
184
-</Tabs>
185
-
186
-For toolkits you haven't white-labeled, use the auth config ID from **Authentication management** in your dashboard.
187
-</Step>
188
-</Steps>
19
+[Create a custom auth config](/docs/authentication/white-labeling-authentication#using-your-own-oauth-apps) with your provider's client credentials to show your app identity on the consent screen. Pass that config's ID when starting the connection. The provider's registered redirect URI must exactly match `oauth_redirect_uri` in the auth config.
20
21
### When to use your own OAuth apps
22
192
-- **Production apps** where end users see consent screens. They should see your brand, not Composio's.
193
-- **Enterprise customers** who require your branding end-to-end.
194
-- **Toolkits where you need custom scopes** beyond what Composio's default app provides.
195
-
196
-For development and testing, Composio's managed auth works fine. No OAuth app setup required.
23
+Use custom credentials when your product needs its own consent-screen identity, scopes, or quotas, or when you need the supported direct-initiation path for an app-owned UI. API-key toolkits don't have an OAuth consent screen.
24
25
### Switching from Composio-managed to your own OAuth app
26
200
-Existing connected accounts are permanently tied to the auth config they were created with. Switching to a custom auth config does not affect them.
201
-
202
-- Existing connections keep working. Tokens continue refreshing using the original auth config's credentials.
203
-- New connections use your custom auth config. Users who connect after the switch will see your app name on the consent screen.
204
-- To fully migrate a user, delete their old connected account and have them re-authenticate through your OAuth app.
27
+Existing connected accounts remain tied to their original auth config. New connections can use the custom config; a branding change doesn't migrate existing accounts. See [Switching auth configs](/docs/authentication/white-labeling-authentication#switching-from-composio-managed-to-your-own-oauth-app).
28
29
## Sending users directly to the OAuth provider
30
208
-By default, when you initiate a connection, Composio returns a shortened redirect URL (`backend.composio.dev/api/v3/s/...`). The user's browser hits this URL first, then gets redirected to the OAuth provider. This means `backend.composio.dev` briefly appears in the browser.
209
-
210
-To skip this and send users directly to the OAuth provider, pass `long_redirect_url: true` when initiating the connection:
211
-
212
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
213
-<Tab value="Python">
214
-```python
215
-from composio import Composio
216
-
217
-composio = Composio(api_key="your_api_key")
31
+For supported custom OAuth2 configs, `connectedAccounts.initiate()` accepts `config.val.long_redirect_url: true` to request an unshortened authorization URL. Your app can render the connect button, required fields, progress, and result screens instead of using Connect Link. Follow [Build an app-owned connection UI](/docs/authentication/white-labeling-authentication#build-an-app-owned-connection-ui) for cURL and SDK examples.
32
219
-github_conn = composio.connected_accounts.initiate(
220
- user_id="user_123",
221
- auth_config_id="ac_your_github_config",
222
- config={
223
- "auth_scheme": "OAUTH2",
224
- "val": {"status": "INITIALIZING", "long_redirect_url": True},
225
- },
226
-)
227
-print(f"Redirect to: {github_conn.redirect_url}")
228
-```
229
-</Tab>
230
-<Tab value="TypeScript">
231
-```typescript
232
-import { Composio } from '@composio/core';
233
-const composio = new Composio({ apiKey: 'your_api_key' });
234
-// ---cut---
235
-const githubConn = await composio.connectedAccounts.initiate(
236
- "user_123",
237
- "ac_your_github_config",
238
- {
239
- config: {
240
- authScheme: "OAUTH2",
241
- // val fields use snake_case; they're sent to the API as-is
242
- val: { status: "INITIALIZING", long_redirect_url: true },
243
- },
244
- },
245
-);
246
-console.log("Redirect to:", githubConn.redirectUrl);
247
-```
248
-</Tab>
249
-</Tabs>
250
-
251
-The redirect URL returned will point directly to the OAuth provider (e.g., `accounts.google.com/o/oauth2/auth?...`) instead of going through Composio first.
33
+`long_redirect_url` controls URL shortening. It doesn't remove Composio's return callback or guarantee that every toolkit skips every intermediate page. Inspect the actual URL chain for each toolkit. The Composio-managed OAuth path of `initiate()` has been retired; use `link()` for managed OAuth. See [Migrating from initiate to link](/docs/auth-configuration/migrating-initiate-to-link).
34
35
## Routing the callback through your domain
36
255
-After the user authorizes, the OAuth provider redirects back through `backend.composio.dev` so Composio can capture the auth token. Some toolkits also display this URL on the consent screen.
256
-
257
-If you need to hide Composio's domain from this return redirect, you can proxy it through your own domain.
258
-
259
-<Steps>
260
-<Step>
261
-<StepTitle>Set the redirect URI to your domain</StepTitle>
262
-
263
-In your OAuth app's settings, set the authorized redirect URI to your own endpoint:
264
-
265
-```
266
-https://yourdomain.com/api/composio-redirect
267
-```
268
-</Step>
269
-
270
-<Step>
271
-<StepTitle>Create a proxy endpoint</StepTitle>
272
-
273
-This endpoint receives the OAuth callback and immediately 302-redirects it to Composio:
274
-
275
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
276
-<Tab value="Python">
277
-```python
278
-from fastapi import FastAPI, Request
279
-from fastapi.responses import RedirectResponse
280
-
281
-app = FastAPI()
282
-
283
-@app.get("/api/composio-redirect")
284
-def composio_redirect(request: Request):
285
- composio_url = "https://backend.composio.dev/api/v3/toolkits/auth/callback"
286
- return RedirectResponse(url=f"{composio_url}?{request.url.query}")
287
-```
288
-</Tab>
289
-<Tab value="TypeScript">
290
-```typescript
291
-// pages/api/composio-redirect.ts (Next.js)
292
-import type { NextApiRequest, NextApiResponse } from "next";
293
-
294
-export default function handler(req: NextApiRequest, res: NextApiResponse) {
295
- const composioUrl = "https://backend.composio.dev/api/v3/toolkits/auth/callback";
296
- const params = new URLSearchParams(req.query as Record<string, string>);
297
- res.redirect(302, `${composioUrl}?${params.toString()}`);
298
-}
299
-```
300
-</Tab>
301
-</Tabs>
302
-
303
-<Callout type="warn">
304
-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.
305
-</Callout>
306
-</Step>
307
-
308
-<Step>
309
-<StepTitle>Update your auth config</StepTitle>
310
-
311
-In the Composio dashboard, update your auth config to use your custom redirect URI.
312
-
313
-<Figure src="/images/custom-redirect-uri.png" alt="Auth Config Settings" caption="Setting the custom redirect URI in your auth config" size="sm" />
314
-</Step>
315
-</Steps>
37
+A custom provider callback endpoint can forward the browser to Composio with a 302 response where the toolkit supports it. This **does not hide `backend.composio.dev`**: the browser still visits Composio after your endpoint. Your endpoint receives the authorization `code` and `state`, so its query string must not be captured in application, CDN, analytics, or error logs.
38
317
-Here's how the redirect flow works. Your proxy just forwards the browser redirect to Composio. It never touches the authorization code or token.
39
+See [Callback domains and forwarding](/docs/authentication/white-labeling-authentication#routing-the-callback-through-your-domain) for the supported response shape and the difference between the provider's `redirect_uri` and your application's `callbackUrl`. Use the latter to return to your own result page after authentication, not to replace the provider callback.
40
319
-<WhiteLabelFlow />
41
+## Verify before enabling access
42
321
-<Callout type="info">
322
-For FAQs and setup guides for individual toolkits, browse the [toolkits page](/toolkits).
323
-</Callout>
43
+Save each connection attempt against the authenticated application user on your server. Don't trust callback query parameters alone. [Verify the saved account ID, user binding, auth config, toolkit, and active status](/docs/authentication/white-labeling-authentication#verify-the-connection-on-your-server) before using it for direct tool execution. Apply any provider-identity policy separately, and complete the [deployment checklist](/docs/authentication/white-labeling-authentication#deployment-checklist).
44
45
## Next
46
docs/content/docs/authentication/white-labeling-authentication.mdx
+189
-105
@@ -1,28 +1,41 @@
1
---
2
title: White-labeling authentication
3
-description: Remove Composio branding from your auth flows
4
-keywords: [branding, own oauth, custom redirect, white label]
3
+description: Brand hosted Connect Link or build your own connection UI with custom OAuth apps and explicit callback-domain limits
4
+keywords: [branding, own oauth, custom redirect, white label, app-owned connection UI]
5
---
6
7
-There are four places where Composio branding shows up during authentication:
7
+You can brand the hosted Connect Link or build your own connection UI with a custom OAuth app. Neither option removes the provider's sign-in and consent screens, and a callback forwarder still sends the browser to Composio.
8
9
-| Where | What users see | How to fix |
10
-|-------|---------------|------------|
11
-| [**Connect Link page**](#customizing-the-connect-link) | Composio logo, name, and styling on the hosted auth page | Set your logo, app title, and theme in the dashboard |
12
-| [**OAuth consent screen**](#using-your-own-oauth-apps) | "Composio wants to access your account" on Google, GitHub, etc. | Use your own OAuth app |
13
-| [**Browser address bar**](#routing-the-callback-through-your-domain) | `backend.composio.dev` flashes during OAuth redirect-back | Proxy the redirect through your domain |
14
-| [**Post-auth success page**](#redirecting-users-after-authentication) | Composio-branded success page after OAuth completes | Pass a `callbackUrl` when initiating the connection |
9
+## Choose your connection UI
10
16
-## Start with the smallest setup
11
+| Mode | How you start it | What you control | What remains external |
12
+|------|------------------|------------------|-----------------------|
13
+| Branded hosted Connect Link | `session.authorize()` or `connectedAccounts.link()` | Logo, app title, theme, and your post-auth page | Composio hosts the connection UI; the provider hosts sign-in and consent |
14
+| App-owned connection UI | `connectedAccounts.initiate()` with your custom OAuth config, where supported | Your connect button, any required input form, progress, and success/error screens | Provider sign-in and consent, plus Composio's OAuth callback |
15
18
-You do not need every option to launch a branded connection flow. Apply only the layers your users will see:
16
+For the hosted path, create an auth config, then run this on your server with a project API key:
17
20
-1. Set your app title, logo, and theme for the hosted Connect Link.
21
-2. Add your own OAuth app only for toolkits where the provider consent screen must show your brand.
22
-3. Add a redirect proxy only when the browser must stay on your domain during the OAuth callback.
23
-4. Pass a `callbackUrl` when users should return directly to your product after connecting.
18
+```bash
19
+export COMPOSIO_API_KEY="your_project_api_key"
20
25
-Start with Connect Link branding, then test the complete flow for one representative OAuth toolkit. Add the other layers only if that test exposes Composio branding you need to remove.
21
+curl --request POST \
22
+ --url https://backend.composio.dev/api/v3/connected_accounts/link \
23
+ --header "x-api-key: $COMPOSIO_API_KEY" \
24
+ --header "Content-Type: application/json" \
25
+ --data '{
26
+ "auth_config_id": "ac_your_github_config",
27
+ "user_id": "user_123",
28
+ "callback_url": "https://your-app.com/connections/callback"
29
+ }' | jq '{connected_account_id, redirect_url}'
30
+```
31
+
32
+This example requires cURL and `jq`. Replace the auth config ID with your project's config and derive `user_id` from your authenticated application session, not a browser-supplied field. Store the returned `connected_account_id` against that user on your server before sending the browser to `redirect_url`. [Verify the connection](#verify-the-connection-on-your-server) before showing success.
33
+
34
+Use [your own OAuth app](#using-your-own-oauth-apps) to change the provider consent-screen identity in either mode. Use an application `callbackUrl` to return to your product after authentication. If you don't want the hosted connection page, follow [Build an app-owned connection UI](#build-an-app-owned-connection-ui).
35
+
36
+<Callout type="warn" title="Branding is not domain replacement">
37
+Connect Link branding doesn't change its `connect.composio.dev` host. A custom OAuth app doesn't remove provider domains or Composio's callback domain. The setup below doesn't provide a CNAME or a self-hosted Connect Link.
38
+</Callout>
39
40
## Customizing the Connect Link
41
@@ -38,7 +51,7 @@ Everything here lives in **Project Settings** → [**White Labeling**](https://d
51
The logo replaces the Composio mark at the top of the page, and the app title replaces "Composio" in the "...wants to connect to your account" heading.
52
53
<Callout>
41
-This 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).
54
+This only changes the Composio-hosted page. The provider's consent screen gets its app identity from the OAuth credentials, not this theme. To change that identity, set up [your own OAuth app](#using-your-own-oauth-apps).
55
</Callout>
56
57
### Colors, fonts, and per-element styling
@@ -105,7 +118,7 @@ if (connectionRequest.redirectUrl) {
118
The `locale` parameter changes only the Connect Link's own text. Field names and help text on API key forms, error details from the provider, and the provider's own sign-in and consent screens keep their original language.
119
120
<Callout type="warn" title="Troubleshooting">
108
-- **"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).
121
+- **The provider consent screen still shows Composio:** configure [your own OAuth app](#using-your-own-oauth-apps), and confirm the connection uses that auth config.
122
- **Logo doesn't appear after uploading:** clear your browser cache or try incognito.
123
- **Upload fails with "failed to fetch":** retry or use a smaller image.
124
- **You see the Branding tab but no Styling tab:** theming is still rolling out. If it isn't enabled for your project yet, reach out. The logo and app title keep working in the meantime.
@@ -113,13 +126,38 @@ The `locale` parameter changes only the Connect Link's own text. Field names and
126
127
## Using your own OAuth apps
128
116
-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, create a custom auth config with your own OAuth credentials and pass that auth config when creating a session.
129
+OAuth providers get the consent-screen name, logo, and publisher identity from your OAuth app, not the Connect Link theme. Register your own app and create a custom auth config to use it.
130
131
<Callout type="info" title="You don't need this for every toolkit">
132
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.
133
</Callout>
134
122
-<Card icon={<Key />} title="Managed vs custom auth" href="/docs/authentication/custom-app-vs-managed-app" description="Decide when to use custom credentials, create an auth config, and pass it to sessions." />
135
+### Create the custom auth config
136
+
137
+1. Register an OAuth app in the provider's developer portal. Configure its name, logo, support details, and the scopes your product needs. Complete any provider verification or publishing requirements before offering it to customers.
138
+2. Register `https://backend.composio.dev/api/v3/toolkits/auth/callback` as the provider's authorized redirect URI. Set this same URL explicitly as `oauth_redirect_uri` in Composio. Some toolkit defaults use the supported legacy callback `/api/v1/auth-apps/add`; don't rely on a default that differs from your provider registration.
139
+3. In the [dashboard's auth configs](https://dashboard.composio.dev/~/project/auth-configs?utm_source=docs&utm_medium=content&utm_campaign=docs-white-labeling-authentication), create an auth config for the toolkit. Select **OAuth2**, enable **Use your own developer credentials**, and enter the client ID, client secret, scopes, and redirect URI. Copy the resulting `ac_...` ID.
140
+4. Keep the client secret and Composio API key on your server. Use separate OAuth apps and auth configs for environments that need different credentials or redirect URIs.
141
+
142
+For code-based provisioning, see [Programmatic auth configs](/docs/authentication/programmatic-auth-configs#your-own-oauth2-credentials). Provider requirements vary; use the [toolkit's authentication guide](/toolkits) for supported schemes and required fields.
143
+
144
+For sessions, select the custom config explicitly:
145
+
146
+```typescript
147
+import { Composio } from '@composio/core';
148
+
149
+const composio = new Composio();
150
+const session = await composio.create('user_123', {
151
+ authConfigs: { github: 'ac_your_github_config' },
152
+});
153
+const request = await session.authorize('github', {
154
+ callbackUrl: 'https://your-app.com/connections/callback',
155
+});
156
+```
157
+
158
+Set `COMPOSIO_API_KEY` in your server environment. Persist `request.id` with the authenticated user's connection attempt, then send the browser to `request.redirectUrl`. Without a session, use `connectedAccounts.link(userId, authConfigId, { callbackUrl })` or the cURL example above. These methods return a hosted Connect Link, not a page you host.
159
+
160
+<Card icon={<Key />} title="Managed vs custom auth" href="/docs/authentication/custom-app-vs-managed-app" description="Choose which toolkits use your OAuth credentials." />
161
162
### Switching from Composio-managed to your own OAuth app
163
@@ -129,131 +167,177 @@ Existing connected accounts are tied to the auth config they were created with.
167
- Existing connections continue refreshing with their original auth config.
168
- To fully migrate an existing user, delete the old connected account and have them re-authenticate with the new auth config, or import their credentials into the new config where supported.
169
132
-## Routing the callback through your domain
170
+## Build an app-owned connection UI
171
134
-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.
172
+For a toolkit that supports direct OAuth2 initiation with custom credentials, you can skip Connect Link and start authorization from your own UI. You own the connection form and status screens, but not the provider's sign-in or consent screen.
173
136
-If you need to hide Composio's domain, you can proxy the redirect through your own domain instead.
174
+<Callout type="warn" title="Use a custom auth config for this path">
175
+`initiate()` remains supported for custom auth configs. Its Composio-managed OAuth path has been retired. Use `link()` or `session.authorize()` for managed OAuth; don't treat them as a way to render the hosted UI inside your own app. See [Migrating from initiate to link](/docs/auth-configuration/migrating-initiate-to-link).
176
+</Callout>
177
138
-<Steps>
139
-<Step>
140
-<StepTitle>Set the redirect URI to your domain</StepTitle>
178
+### Start authorization from your backend
179
+
180
+1. Render your own **Connect GitHub** button and any toolkit-required fields. Check the toolkit's authentication requirements first; a generic button isn't enough for providers that require an account URL, shop name, or other initialization data.
181
+2. When the signed-in user clicks, authorize the request in your backend. Select the toolkit and custom auth config from server-controlled values.
182
+3. Create a connection using `initiate()`. Set `long_redirect_url` to request an unshortened authorization URL:
183
+
184
+```bash
185
+curl --request POST \
186
+ --url https://backend.composio.dev/api/v3/connected_accounts \
187
+ --header "x-api-key: $COMPOSIO_API_KEY" \
188
+ --header "Content-Type: application/json" \
189
+ --data '{
190
+ "auth_config": {"id": "ac_your_github_config"},
191
+ "connection": {
192
+ "user_id": "user_123",
193
+ "callback_url": "https://your-app.com/connections/callback",
194
+ "state": {
195
+ "authScheme": "OAUTH2",
196
+ "val": {"status": "INITIALIZING", "long_redirect_url": true}
197
+ }
198
+ }
199
+ }' | jq '{id, redirect_url: .connectionData.val.redirectUrl}'
200
+```
201
142
-In your OAuth app's settings, set the authorized redirect URI to your own endpoint:
202
+The SDK equivalent is:
203
204
+```typescript
205
+import { Composio } from '@composio/core';
206
+
207
+const composio = new Composio();
208
+const request = await composio.connectedAccounts.initiate(
209
+ 'user_123',
210
+ 'ac_your_github_config',
211
+ {
212
+ callbackUrl: 'https://your-app.com/connections/callback',
213
+ config: {
214
+ authScheme: 'OAUTH2',
215
+ val: { status: 'INITIALIZING', long_redirect_url: true },
216
+ },
217
+ },
218
+);
219
```
145
-https://yourdomain.com/api/composio-redirect
146
-```
147
-</Step>
220
149
-<Step>
150
-<StepTitle>Create a proxy endpoint</StepTitle>
221
+4. Store the returned `id`, authenticated application user, expected toolkit, and auth config as a pending attempt on your server. Return only the authorization URL to your frontend and navigate the browser to it. Don't send the raw API response or credentials to the browser or a model.
222
+5. On return to your application callback, [verify the stored attempt and connected account](#verify-the-connection-on-your-server), then render your own result page. If the browser closes or never returns, keep the attempt pending until your application expires it; don't infer success.
223
152
-This endpoint receives the OAuth callback and immediately 302-redirects it to Composio:
224
+For supported direct OAuth flows, the unshortened URL points to the provider rather than Composio's short-link redirect. Inspect the returned URL and test each toolkit before deployment. `long_redirect_url` controls URL shortening; it isn't a guarantee that every toolkit can skip all intermediate pages, and it doesn't change the return callback.
225
154
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
155
-<Tab value="Python">
156
-```python
157
-from fastapi import FastAPI, Request
158
-from fastapi.responses import RedirectResponse
226
+### Use the connection in a session
227
160
-app = FastAPI()
228
+After verification, pass the connected account ID to a session for the same server-derived user:
229
162
-@app.get("/api/composio-redirect")
163
-def composio_redirect(request: Request):
164
- composio_url = "https://backend.composio.dev/api/v3/toolkits/auth/callback"
165
- return RedirectResponse(url=f"{composio_url}?{request.url.query}")
166
-```
167
-</Tab>
168
-<Tab value="TypeScript">
230
```typescript
170
-// pages/api/composio-redirect.ts (Next.js)
171
-import type { NextApiRequest, NextApiResponse } from "next";
231
+import { Composio } from '@composio/core';
232
173
-export default function handler(req: NextApiRequest, res: NextApiResponse) {
174
- const composioUrl = "https://backend.composio.dev/api/v3/toolkits/auth/callback";
175
- const params = new URLSearchParams(req.query as Record<string, string>);
176
- res.redirect(302, `${composioUrl}?${params.toString()}`);
177
-}
233
+const composio = new Composio();
234
+const session = await composio.create('user_123', {
235
+ authConfigs: { github: 'ac_your_github_config' },
236
+ connectedAccounts: { github: 'ca_verified_github_account' },
237
+});
238
```
179
-</Tab>
180
-</Tabs>
239
182
-<Callout type="warn">
183
-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.
184
-</Callout>
185
-</Step>
240
+Replace `ca_verified_github_account` with the ID your backend verified, not a browser-selected account. If you want to keep connection UI app-owned, initiate missing connections from your app rather than calling `session.authorize()`, which starts the hosted flow.
241
187
-<Step>
188
-<StepTitle>Update your auth config</StepTitle>
242
+## Routing the callback through your domain
243
190
-In the Composio dashboard, update your auth config to use your custom redirect URI.
244
+There are two different callback URLs:
245
192
-<Figure src="/images/custom-redirect-uri.png" alt="Auth Config Settings" caption="Setting the custom redirect URI in your auth config" size="sm" />
193
-</Step>
194
-</Steps>
246
+| Setting | Who redirects to it | Purpose |
247
+|---------|---------------------|---------|
248
+| Provider `redirect_uri`, configured as `oauth_redirect_uri` in your auth config | OAuth provider | Receives the OAuth authorization response so Composio can complete the token exchange |
249
+| Application `callbackUrl` (`callback_url` in REST/Python) | Composio after authentication | Returns the browser to your product so your backend can verify the result and show your UI |
250
196
-Here's how the redirect flow works. Your proxy just forwards the browser redirect to Composio. It never touches the authorization code or token.
251
+Changing the application `callbackUrl` doesn't change the provider's `redirect_uri`. With the default provider callback, a direct flow follows:
252
198
-<WhiteLabelFlow />
253
+```mermaid
254
+flowchart LR
255
+ A["Your app"] --> P["Provider sign-in and consent"]
256
+ P --> C["backend.composio.dev/api/v3/toolkits/auth/callback"]
257
+ C --> R["your-app.com/connections/callback"]
258
+```
259
+
260
+The hosted path adds `connect.composio.dev` before the provider, and may show hosted completion UI when no application callback is set. Short links and provider-specific steps may add other hops.
261
+
262
+### Optional: register your own provider callback endpoint
263
+
264
+If the toolkit and provider support a custom redirect URI, you can register an HTTPS endpoint you control, such as `https://your-app.com/oauth/provider-callback`, in both the provider's OAuth app and the auth config's `oauth_redirect_uri`.
265
+
266
+For an OAuth2 provider that returns the authorization response in a GET query, that endpoint must return a browser redirect to the fixed Composio callback, preserving the original query string, including `code`, `state`, or provider error parameters:
267
+
268
+```http
269
+HTTP/1.1 302 Found
270
+Location: https://backend.composio.dev/api/v3/toolkits/auth/callback?<original-query-string>
271
+Cache-Control: no-store
272
+Referrer-Policy: no-referrer
273
+```
274
+
275
+This is a response shape, not a literal `Location` value. Append the original query without decoding and reconstructing its values. Keep the destination fixed; don't accept a redirect target from the incoming request. Don't exchange the code in this endpoint, fetch the callback server-side, or consume the provider's `state` as your application's attempt identifier.
276
200
-<Callout type="info">
201
-For FAQs and setup guides for individual toolkits, browse the [toolkits page](/toolkits).
277
+<Callout type="warn" title="A 302 forwarder does not hide Composio">
278
+The browser still visits `backend.composio.dev` after your endpoint. Your endpoint receives the authorization `code` and `state` in the request, even though it doesn't exchange the code for tokens. Disable query-string capture in access logs, error reports, analytics, and tracing for this route, including any CDN or reverse proxy in front of it. Don't render a page or load third-party resources before forwarding.
279
</Callout>
280
281
+The custom endpoint changes the redirect URI registered with the provider and adds a browser hop. It doesn't make OAuth app-only or remove Composio from the address bar. Don't use this GET-query forwarding pattern for providers with a different response mode without confirming toolkit support.
282
+
283
+<WhiteLabelFlow />
284
+
285
## Redirecting users after authentication
286
206
-By default, after OAuth completes, users land on a Composio-hosted success page that shows Composio branding. To bypass this page and send users to your own domain instead, pass a `callbackUrl` when calling `session.authorize()`:
287
+Pass an application `callbackUrl` when starting either flow to return to your product instead of the default hosted success page. The examples above use `https://your-app.com/connections/callback`. Keep this URL server-controlled, or validate it against an allowlist if your application supports multiple return destinations.
288
208
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
209
-<Tab value="Python">
210
-```python
211
-connection_request = session.authorize(
212
- "gmail",
213
- callback_url="https://your-app.com/callback"
214
-)
215
-```
216
-</Tab>
217
-<Tab value="TypeScript">
218
-```typescript
219
-import { Composio } from '@composio/core';
220
-const composio = new Composio({ apiKey: 'your_api_key' });
221
-const session = await composio.create("user_123");
222
-// ---cut---
223
-const connectionRequest = await session.authorize("gmail", {
224
- callbackUrl: "https://your-app.com/callback",
225
-});
226
-```
227
-</Tab>
228
-</Tabs>
289
+The callback can include `status=success` or `status=failed` and `connected_account_id`. Treat these as navigation hints, not proof that the connection is active or belongs to the current user. See [callback parameters](/docs/authentication/manually-authenticating#redirecting-users-after-authentication).
290
230
-After authentication, Composio redirects the user to your callback URL instead of the default success page. For full details on the parameters appended to your callback URL, see [Manually authenticating users → Redirecting users after authentication](/docs/authentication/manually-authenticating#redirecting-users-after-authentication).
291
+## Verify the connection on your server
292
232
-## Frequently asked questions
293
+Before marking an integration connected:
294
234
-### Do I need a custom OAuth app for every toolkit?
295
+1. Require your application's authenticated session. Retrieve its pending connection attempt from server-side storage. If you need to distinguish simultaneous attempts, include a fresh, unguessable attempt ID in your application `callbackUrl`, bind it to that session, and expire it after use. This is separate from the provider's OAuth `state`.
296
+2. Match any callback `connected_account_id` against the ID saved when your backend started the attempt. Don't trust a callback `user_id`, an account ID from the browser, or `status=success` on its own.
297
+3. Query Composio with your project API key, filtering by the saved account ID, the server-derived user, expected auth config, toolkit, and `ACTIVE` status:
298
236
-No. Create one only for OAuth toolkits where users see a provider consent screen and your product needs its own branding, scopes, or quotas. API-key toolkits do not have an OAuth consent screen. You can mix managed and custom auth configs in the same project.
299
+```bash
300
+curl --get \
301
+ --url https://backend.composio.dev/api/v3/connected_accounts \
302
+ --header "x-api-key: $COMPOSIO_API_KEY" \
303
+ --data-urlencode "connected_account_ids=ca_saved_connection_id" \
304
+ --data-urlencode "user_ids=user_123" \
305
+ --data-urlencode "auth_config_ids=ac_your_github_config" \
306
+ --data-urlencode "toolkit_slugs=github" \
307
+ --data-urlencode "statuses=ACTIVE" \
308
+ | jq '{items: [.items[] | {id, status, is_disabled, toolkit, auth_config}]}'
309
+```
310
238
-### Does changing the Connect Link logo change the provider consent screen?
311
+4. Require the saved account ID in the result, with the expected toolkit, auth config, and `ACTIVE` status. Require both the connection and auth config to be enabled (`is_disabled: false`). An empty result isn't success. The `user_id` field on individual account responses is deprecated, so don't rely on it being returned; use the user filter and your stored user-to-attempt binding.
312
+5. Mark the attempt complete once and show your success UI. If it's still pending, show progress and check again from your backend. Handle failed, expired, cancelled, and abandoned attempts without enabling tool access.
313
240
-No. Connect Link branding changes the Composio-hosted connection page. Google, GitHub, Slack, and other OAuth providers get their consent-screen identity from the OAuth app. Use [your own OAuth app](#using-your-own-oauth-apps) to change it.
314
+This binds the connection to your *application* user. It doesn't prove which Google or GitHub identity they selected. If your product restricts the provider identity, fetch the provider's authenticated current-user profile using the verified connection and enforce that policy before enabling access. See [Identify the connected account](/docs/authentication/manually-authenticating#identify-the-connected-account). A display name or alias alone isn't an identity check.
315
242
-### Can each customer have different branding?
316
+Keep Composio API keys, OAuth client secrets, and tokens out of frontend code, model prompts, tool arguments, and logs. Handle authorization codes only in the callback route; don't copy them into UI payloads or model context. Return only the sanitized status and account label your UI needs.
317
244
-Each Composio project has one app title, logo, and theme. If separate products or customers need independent branding, use separate projects and account for the additional provisioning and credential management.
318
+## Deployment checklist
319
246
-### What happens to existing connections when I switch auth configs?
320
+- **Consent:** Check the provider's actual consent screen for your app name, publisher details, and requested scopes. Complete required verification and test with an account outside your developer team.
321
+- **URL chain:** Record the real browser navigation for each supported toolkit, including short links, Connect Link if used, provider domains, any forwarder, Composio's callback, and your application callback. Don't promise zero third-party domains.
322
+- **Redirect configuration:** Match the provider registration and auth config's `oauth_redirect_uri` exactly. Confirm that the separate application `callbackUrl` is allowlisted and returns to your product.
323
+- **Connection outcomes:** Exercise success, consent denial, provider error, closed tabs, expired attempts, and retries. Don't assume every cancellation produces a callback.
324
+- **Ownership and status:** Reject mismatched attempt IDs, users, connected account IDs, toolkits, and auth configs. Enable access only after your backend finds the expected active connection and applies any provider-identity policy.
325
+- **Secrets and logging:** Confirm no API key, client secret, or token reaches the frontend or model. Keep authorization codes confined to the callback route, and check CDN, application, analytics, and error logs for callback query capture.
326
+- **Existing connections:** Test new connections with the custom config separately from accounts created with the old config. A branding change doesn't migrate them.
327
248
-They remain tied to the auth config used when they were created. New connections can use the custom config, while existing users continue with their current connected accounts until they re-authenticate or you migrate their credentials where supported.
328
+## Frequently asked questions
329
250
-### How do I remove the Composio domain and success page?
330
+### Do I need a custom OAuth app for every toolkit?
331
+
332
+No. Use one for OAuth toolkits where your product needs its own consent-screen identity, scopes, or quotas. API-key toolkits don't have an OAuth consent screen. You can mix managed and custom auth configs.
333
+
334
+### Can each customer have different branding?
335
252
-Use a [redirect proxy](#routing-the-callback-through-your-domain) to keep the browser callback on your domain. Pass a [`callbackUrl`](#redirecting-users-after-authentication) to return users directly to your product after authentication. These solve separate parts of the redirect flow.
336
+Each Composio project has one Connect Link app title, logo, and theme. Use separate projects if hosted flows need independent branding, and account for the extra provisioning. An app-owned UI controls its own appearance independently of the hosted theme.
337
254
-### Why does the "Secured by Composio" badge still appear?
338
+### Can I remove every Composio domain with a redirect forwarder?
339
256
-Connect Link styling alone does not remove it. Configure your own OAuth app for that toolkit so the provider consent flow uses your credentials and identity.
340
+No. A 302 forwarder still navigates the browser to Composio. An app-owned UI can skip the hosted Connect Link for supported custom OAuth flows, but Composio's callback and the provider's pages remain part of the flow described here.
341
342
## Next
343
docs/kb/articles/platform-google-oauth.md
+5
-3
@@ -14,9 +14,11 @@ and [sensitive-scope verification guide](https://developers.google.com/identity/
14
## A customer-owned OAuth app controls the provider consent-screen brand
15
16
Use a customer-owned Google OAuth app when the Google consent screen should
17
-show the customer's app name and branding. To avoid showing a Composio domain
18
-in the redirect path as well, route the callback through the customer's domain
19
-as described in [white-labeling authentication](https://docs.composio.dev/docs/white-labeling-authentication#routing-the-callback-through-your-domain).
17
+show the customer's app name and branding. A callback forwarder on the
18
+customer's domain still redirects the browser to Composio; it does not hide
19
+Composio's domain. The forwarding endpoint receives the authorization code and
20
+state, so its query string must not be logged. See
21
+[callback-domain limits](/docs/authentication/white-labeling-authentication#routing-the-callback-through-your-domain).
22
23
The OAuth app's authorized redirect URI must still match the callback URI
24
shown by Composio. Provider consent-screen branding and the URL to which the