Skip to content

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

Sushmithamalleshb2cdfd2baa7c
diff --git a/docs/content/docs/authenticating-users/manually-authenticating.mdx b/docs/content/docs/authenticating-users/manually-authenticating.mdx
index 5b1171100..2742eda80 100644
--- a/docs/content/docs/authenticating-users/manually-authenticating.mdx
+++ b/docs/content/docs/authenticating-users/manually-authenticating.mdx
@@ -50,6 +50,47 @@ Redirect the user to the redirect URL. After they authenticate, they'll return t
If the user closes the Connect Link without completing auth, the connection remains in `INITIATED` status until it expires.
</Callout>
+## Callback URL
+
+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.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+connection_request = session.authorize(
+ "gmail",
+ callback_url="https://your-app.com/callback?user_id=user_123&source=onboarding"
+)
+
+print(connection_request.redirect_url)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+const session = await composio.create("user_123");
+// ---cut---
+const connectionRequest = await session.authorize("gmail", {
+ callbackUrl: "https://your-app.com/callback?user_id=user_123&source=onboarding",
+});
+
+console.log(connectionRequest.redirectUrl);
+```
+</Tab>
+</Tabs>
+
+After authentication, Composio redirects the user to your callback URL with the following parameters appended, while preserving your existing ones:
+
+| Parameter | Description |
+|-----------|-------------|
+| `status` | `success` or `failed` |
+| `connected_account_id` | The ID of the newly created connected account |
+
+```
+https://your-app.com/callback?user_id=user_123&source=onboarding&status=success&connected_account_id=ca_abc123
+```
+
## Check connection status
Use `session.toolkits()` to see all toolkits in the session and their connection status:
diff --git a/docs/content/docs/tools-direct/authenticating-tools.mdx b/docs/content/docs/tools-direct/authenticating-tools.mdx
index 44180dac8..1d0166d9d 100644
--- a/docs/content/docs/tools-direct/authenticating-tools.mdx
+++ b/docs/content/docs/tools-direct/authenticating-tools.mdx
@@ -162,6 +162,21 @@ These settings will apply to all authentication flows using Connect Link, provid
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>
+#### Passing query parameters in the callback URL
+
+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:
+
+| Parameter | Description |
+|-----------|-------------|
+| `status` | `success` or `failed` |
+| `connected_account_id` | The ID of the newly created connected account |
+
+For example, if your callback URL is `https://your-app.com/callback?user_id=user_123`, the redirect after successful auth will be:
+
+```
+https://your-app.com/callback?user_id=user_123&status=success&connected_account_id=ca_abc123
+```
+
### Direct SDK Setup
**Choose the section below that matches your toolkit's authentication method:**
@@ -233,6 +248,10 @@ console.log(`Connection established: ${connectedAccount.id}`);
</Tab>
</Tabs>
+<Callout type="info">
+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.
+</Callout>
+
#### Services with Additional Parameters
Some services like Zendesk require additional parameters such as `subdomain`: