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(auth): note the create-time callback_url is unused with a verifier URL

Anshu Garg29af2cdbebf6
diff --git a/docs/api-overviews/connected-accounts.mdx b/docs/api-overviews/connected-accounts.mdx
index f0d33ab7e..29cfa9af3 100644
--- a/docs/api-overviews/connected-accounts.mdx
+++ b/docs/api-overviews/connected-accounts.mdx
@@ -27,6 +27,8 @@ Anyone who opens a Connect Link and consents becomes the account attached to tha
Set a verifier URL on a project, and Composio holds every OAuth connection there until your server confirms who came back. After the provider callback, Composio redirects the browser to the endpoint you host with one query parameter, `session_uri`, which carries no connection id, user id, or toolkit name. From your server, authenticating with your project API key, you post the `session_uri` and the signed-in `user_id` to the [complete auth endpoint](/reference/api-reference/connected-accounts/postConnectedAccountsCompleteAuth). On a match the connection activates and returns its `connected_account_id` and `toolkit_slug`; a `200` comes back only once it is `ACTIVE`. Only a `user_id` that doesn't match fails the connection: the request returns `400`, and the connection moves to `FAILED` with its `status_reason` set to `Callback identity verification failed`. Any other error leaves the connection pending, so you can restart the flow. The `session_uri` is single-use and valid for ten minutes; redeeming it spends the session whatever the outcome, so a repeat call returns `404`.
+Your endpoint owns the redirect from here: once you redeem the session, send the user onward yourself. A `callback_url` set when you create the connection is not used.
+
Turn it on in the dashboard under **Settings → General → Configuration**. The URL must be public HTTPS, and Composio rejects private and reserved addresses on save, so local development needs a tunnel. Verification is opt-in per project, and once set it covers every OAuth connection in the project that goes through a provider redirect, whether you start it from the API or a Connect Link.
<Callout type="warning">
diff --git a/docs/content/reference/api-reference/connected-accounts/index.mdx b/docs/content/reference/api-reference/connected-accounts/index.mdx
index b23aadf4c..2cb152521 100644
--- a/docs/content/reference/api-reference/connected-accounts/index.mdx
+++ b/docs/content/reference/api-reference/connected-accounts/index.mdx
@@ -34,6 +34,8 @@ Anyone who opens a Connect Link and consents becomes the account attached to tha
Set a verifier URL on a project, and Composio holds every OAuth connection there until your server confirms who came back. After the provider callback, Composio redirects the browser to the endpoint you host with one query parameter, `session_uri`, which carries no connection id, user id, or toolkit name. From your server, authenticating with your project API key, you post the `session_uri` and the signed-in `user_id` to the [complete auth endpoint](/reference/api-reference/connected-accounts/postConnectedAccountsCompleteAuth). On a match the connection activates and returns its `connected_account_id` and `toolkit_slug`; a `200` comes back only once it is `ACTIVE`. Only a `user_id` that doesn't match fails the connection: the request returns `400`, and the connection moves to `FAILED` with its `status_reason` set to `Callback identity verification failed`. Any other error leaves the connection pending, so you can restart the flow. The `session_uri` is single-use and valid for ten minutes; redeeming it spends the session whatever the outcome, so a repeat call returns `404`.
+Your endpoint owns the redirect from here: once you redeem the session, send the user onward yourself. A `callback_url` set when you create the connection is not used.
+
Turn it on in the dashboard under **Settings → General → Configuration**. The URL must be public HTTPS, and Composio rejects private and reserved addresses on save, so local development needs a tunnel. Verification is opt-in per project, and once set it covers every OAuth connection in the project that goes through a provider redirect, whether you start it from the API or a Connect Link.
<Callout type="warning">
diff --git a/docs/content/reference/v3/api-reference/connected-accounts/index.mdx b/docs/content/reference/v3/api-reference/connected-accounts/index.mdx
index b3f2cb345..fcc9cc6cd 100644
--- a/docs/content/reference/v3/api-reference/connected-accounts/index.mdx
+++ b/docs/content/reference/v3/api-reference/connected-accounts/index.mdx
@@ -34,6 +34,8 @@ Anyone who opens a Connect Link and consents becomes the account attached to tha
Set a verifier URL on a project, and Composio holds every OAuth connection there until your server confirms who came back. After the provider callback, Composio redirects the browser to the endpoint you host with one query parameter, `session_uri`, which carries no connection id, user id, or toolkit name. From your server, authenticating with your project API key, you post the `session_uri` and the signed-in `user_id` to the [complete auth endpoint](/reference/api-reference/connected-accounts/postConnectedAccountsCompleteAuth). On a match the connection activates and returns its `connected_account_id` and `toolkit_slug`; a `200` comes back only once it is `ACTIVE`. Only a `user_id` that doesn't match fails the connection: the request returns `400`, and the connection moves to `FAILED` with its `status_reason` set to `Callback identity verification failed`. Any other error leaves the connection pending, so you can restart the flow. The `session_uri` is single-use and valid for ten minutes; redeeming it spends the session whatever the outcome, so a repeat call returns `404`.
+Your endpoint owns the redirect from here: once you redeem the session, send the user onward yourself. A `callback_url` set when you create the connection is not used.
+
Turn it on in the dashboard under **Settings → General → Configuration**. The URL must be public HTTPS, and Composio rejects private and reserved addresses on save, so local development needs a tunnel. Verification is opt-in per project, and once set it covers every OAuth connection in the project that goes through a provider redirect, whether you start it from the API or a Connect Link.
<Callout type="warning">