@devries-cameron20 / composio-1 / commits / b2cdfd2ba
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.

docs: document callback URL query parameters for auth flows

Verified across both Python and TS SDKs that Composio preserves custom query params and appends status + connected_account_id on redirect. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmithamallesh committed Feb 11, 2026 at 15:31 UTC b2cdfd2baa7c742cf92d2759e7f174b32c491edc
2 files changed +60
docs/content/docs/authenticating-users/manually-authenticating.mdx
+41
@@ -50,6 +50,47 @@ Redirect the user to the redirect URL. After they authenticate, they'll return t
50 If the user closes the Connect Link without completing auth, the connection remains in `INITIATED` status until it expires.
51 </Callout>
52
53 +## Callback URL
54 +
55 +Pass a `callbackUrl` to control where users land after authenticating. You can include query parameters to carry context through the flow, for example to identify which user or session triggered the connection.
56 +
57 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
58 +<Tab value="Python">
59 +```python
60 +connection_request = session.authorize(
61 + "gmail",
62 + callback_url="https://your-app.com/callback?user_id=user_123&source=onboarding"
63 +)
64 +
65 +print(connection_request.redirect_url)
66 +```
67 +</Tab>
68 +<Tab value="TypeScript">
69 +```typescript
70 +import { Composio } from '@composio/core';
71 +const composio = new Composio({ apiKey: 'your_api_key' });
72 +const session = await composio.create("user_123");
73 +// ---cut---
74 +const connectionRequest = await session.authorize("gmail", {
75 + callbackUrl: "https://your-app.com/callback?user_id=user_123&source=onboarding",
76 +});
77 +
78 +console.log(connectionRequest.redirectUrl);
79 +```
80 +</Tab>
81 +</Tabs>
82 +
83 +After authentication, Composio redirects the user to your callback URL with the following parameters appended, while preserving your existing ones:
84 +
85 +| Parameter | Description |
86 +|-----------|-------------|
87 +| `status` | `success` or `failed` |
88 +| `connected_account_id` | The ID of the newly created connected account |
89 +
90 +```
91 +https://your-app.com/callback?user_id=user_123&source=onboarding&status=success&connected_account_id=ca_abc123
92 +```
93 +
94 ## Check connection status
95
96 Use `session.toolkits()` to see all toolkits in the session and their connection status:
docs/content/docs/tools-direct/authenticating-tools.mdx
+19
@@ -162,6 +162,21 @@ These settings will apply to all authentication flows using Connect Link, provid
162 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).
163 </Callout>
164
165 +#### Passing query parameters in the callback URL
166 +
167 +You can include custom query parameters in your callback URL to carry context through the auth flow, such as identifying which user or session triggered the connection. Composio preserves your parameters and appends its own after authentication completes:
168 +
169 +| Parameter | Description |
170 +|-----------|-------------|
171 +| `status` | `success` or `failed` |
172 +| `connected_account_id` | The ID of the newly created connected account |
173 +
174 +For example, if your callback URL is `https://your-app.com/callback?user_id=user_123`, the redirect after successful auth will be:
175 +
176 +```
177 +https://your-app.com/callback?user_id=user_123&status=success&connected_account_id=ca_abc123
178 +```
179 +
180 ### Direct SDK Setup
181
182 **Choose the section below that matches your toolkit's authentication method:**
@@ -233,6 +248,10 @@ console.log(`Connection established: ${connectedAccount.id}`);
248 </Tab>
249 </Tabs>
250
251 +<Callout type="info">
252 +Your callback URL can include query parameters to carry context through the auth flow. Note that `initiate()` uses camelCase parameters (`connectedAccountId`, `appName`) in the redirect, unlike `link()` which uses snake_case (`connected_account_id`). See [Passing query parameters in the callback URL](#passing-query-parameters-in-the-callback-url) for details.
253 +</Callout>
254 +
255 #### Services with Additional Parameters
256
257 Some services like Zendesk require additional parameters such as `subdomain`: