Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs(auth): v3.1-only section, correct status_reason value, honest changelog
Anshu Garg82558047d8b3
diff --git a/docs/api-overviews/connected-accounts.mdx b/docs/api-overviews/connected-accounts.mdxindex 3dcf3d470..8a56d07b1 100644--- a/docs/api-overviews/connected-accounts.mdx+++ b/docs/api-overviews/connected-accounts.mdx@@ -33,7 +33,7 @@ It has one cost. If a user opens the link in one browser but the provider sends### Callback identity verification-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 `status_reason` set to `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`.+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`.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. A managed connection then gets both checks.diff --git a/docs/content/changelog/07-30-26-oauth-connection-binding.mdx b/docs/content/changelog/07-30-26-oauth-connection-binding.mdxindex 950b4d838..ce15fc1af 100644--- a/docs/content/changelog/07-30-26-oauth-connection-binding.mdx+++ b/docs/content/changelog/07-30-26-oauth-connection-binding.mdx@@ -1,14 +1,14 @@---title: "OAuth connection security: same-browser binding and callback identity verification"date: "2026-07-30"-description: "Stop an OAuth connection from being completed by another party: same-browser binding on Composio managed apps, and opt-in, per-project callback identity verification."+description: "Two controls against OAuth session fixation: same-browser binding, automatic on Composio managed apps, and opt-in callback identity verification per project."----Composio now stops an OAuth connection from being completed by anyone other than the person who-started it. On Composio managed apps this is automatic: the connection is bound to the browser that-began it. And any project can turn on callback identity verification, which ties activation to your-signed-in user. That's the one to reach for on your own OAuth apps, since it checks the user rather-than the browser.+OAuth session fixation lets someone start a connection, hand the authorization URL to another person,+and capture whatever that person connects. Composio now ships two controls against it. Same-browser+binding is automatic on Composio managed apps: a connection has to be finished in the browser that+started it. Callback identity verification is opt-in per project, and it's the one to reach for on+your own OAuth apps, since it ties activation to your signed-in user rather than the browser.### What shippeddiff --git a/docs/content/reference/api-reference/connected-accounts/index.mdx b/docs/content/reference/api-reference/connected-accounts/index.mdxindex bf3fd2ddb..5d6124403 100644--- a/docs/content/reference/api-reference/connected-accounts/index.mdx+++ b/docs/content/reference/api-reference/connected-accounts/index.mdx@@ -40,7 +40,7 @@ It has one cost. If a user opens the link in one browser but the provider sends### Callback identity verification-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 `status_reason` set to `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`.+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`.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. A managed connection then gets both checks.diff --git a/docs/content/reference/v3/api-reference/connected-accounts/index.mdx b/docs/content/reference/v3/api-reference/connected-accounts/index.mdxindex 18e84726a..33d2d9ddf 100644--- a/docs/content/reference/v3/api-reference/connected-accounts/index.mdx+++ b/docs/content/reference/v3/api-reference/connected-accounts/index.mdx@@ -28,26 +28,6 @@ These endpoints use your project API key in the `x-api-key` header.Shared-connection ACL fields are experimental and nested under an `experimental` block on the wire. Pin a specific SDK version if you depend on the current shape.</Callout>-## OAuth connection security--Anyone who opens a Connect Link and consents becomes the account attached to that flow. On its own that is exploitable: someone starts a connection under their own user, copies the authorization URL before consenting, and gets a different person to finish it, attaching that person's provider account under the attacker's identity. Composio guards against this two ways.--### Same-browser binding--On Composio managed apps, a connection has to be finished in the same browser that started it. Composio sets a secure cookie when the Connect Link is submitted and checks it when the provider returns, so a link can't be carried to another browser and completed there. This runs automatically, and you can't turn it off: a managed OAuth app is shared across every Composio user, so without it a connection one person starts could be finished by another.--It has one cost. If a user opens the link in one browser but the provider sends them back to another, the connection is rejected with `This connection was started from a different browser or device`. This usually happens with in-app browsers, such as Instagram or LinkedIn, that hand the provider step to the system browser, or when cookies are blocked. Reopening the link in a single browser gets them through. If it's blocking your users, bring your own OAuth app and turn on callback identity verification, which binds to your signed-in user instead of the browser.--### Callback identity verification--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 `status_reason` set to `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`.--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. A managed connection then gets both checks.--<Callout type="warning">-Connections you start from the dashboard can't complete while a verifier URL is set. A dashboard connection is owned by a Composio dashboard user, which isn't one of your app's users and isn't disclosed to your endpoint, so your app can't report a matching `user_id`. Test from your own app, or clear the verifier URL while you work in the dashboard.-</Callout>-## Endpoints<ApiEndpointsTable endpoints={[{"method":"GET","pathV31":"/api/v3.1/connected_accounts","pathV3":"/api/v3/connected_accounts","summary":"List connected accounts with optional filters","href":"/reference/v3/api-reference/connected-accounts/getConnectedAccounts"},{"method":"POST","pathV31":"/api/v3.1/connected_accounts","pathV3":"/api/v3/connected_accounts","summary":"Create a new connected account","href":"/reference/v3/api-reference/connected-accounts/postConnectedAccounts"},{"method":"GET","pathV31":"/api/v3.1/connected_accounts/{nanoid}","pathV3":"/api/v3/connected_accounts/{nanoid}","summary":"Get connected account details by ID","href":"/reference/v3/api-reference/connected-accounts/getConnectedAccountsByNanoid"},{"method":"DELETE","pathV31":"/api/v3.1/connected_accounts/{nanoid}","pathV3":"/api/v3/connected_accounts/{nanoid}","summary":"Delete a connected account","href":"/reference/v3/api-reference/connected-accounts/deleteConnectedAccountsByNanoid"},{"method":"PATCH","pathV31":"/api/v3.1/connected_accounts/{nanoid}","pathV3":"/api/v3/connected_accounts/{nanoid}","summary":"Update a connected account","href":"/reference/v3/api-reference/connected-accounts/patchConnectedAccountsByNanoid"},{"method":"PATCH","pathV31":"/api/v3.1/connected_accounts/{nanoId}/status","pathV3":"/api/v3/connected_accounts/{nanoId}/status","summary":"Enable or disable a connected account","href":"/reference/v3/api-reference/connected-accounts/patchConnectedAccountsByNanoIdStatus"},{"method":"POST","pathV31":"/api/v3.1/connected_accounts/{nanoid}/refresh","pathV3":"/api/v3/connected_accounts/{nanoid}/refresh","summary":"Re-initiate authentication for a connected account (DEPRECATED)","href":"/reference/v3/api-reference/connected-accounts/postConnectedAccountsByNanoidRefresh","legacy":true},{"method":"POST","pathV31":"/api/v3.1/connected_accounts/link","pathV3":"/api/v3/connected_accounts/link","summary":"Create a new auth link session","href":"/reference/v3/api-reference/connected-accounts/postConnectedAccountsLink"}]} />