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): v3.1-only section, correct status_reason value, honest changelog
- complete_auth is a v3.1-only endpoint (no v3 route), so drop the OAuth connection security section from the v3 connected-accounts index; keep it on v3.1. - status_reason on mismatch is the enum VALUE 'Callback identity verification failed', not the key IDENTITY_VERIFICATION_FAILED. Fix both files. - Changelog no longer claims Composio universally 'stops' the attack. It ships two controls: same-browser binding (automatic on managed) and opt-in callback identity verification.
Anshu Garg committed
Jul 30, 2026 at 18:41 UTC
82558047d8b39f0ee6dc9834d9c376caf30f16e4
4 files changed
+8
-28
docs/api-overviews/connected-accounts.mdx
+1
-1
@@ -33,7 +33,7 @@ It has one cost. If a user opens the link in one browser but the provider sends
33
34
### Callback identity verification
35
36
-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`.
36
+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`.
37
38
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.
39
docs/content/changelog/07-30-26-oauth-connection-binding.mdx
+6
-6
@@ -1,14 +1,14 @@
1
---
2
title: "OAuth connection security: same-browser binding and callback identity verification"
3
date: "2026-07-30"
4
-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."
4
+description: "Two controls against OAuth session fixation: same-browser binding, automatic on Composio managed apps, and opt-in callback identity verification per project."
5
---
6
7
-Composio now stops an OAuth connection from being completed by anyone other than the person who
8
-started it. On Composio managed apps this is automatic: the connection is bound to the browser that
9
-began it. And any project can turn on callback identity verification, which ties activation to your
10
-signed-in user. That's the one to reach for on your own OAuth apps, since it checks the user rather
11
-than the browser.
7
+OAuth session fixation lets someone start a connection, hand the authorization URL to another person,
8
+and capture whatever that person connects. Composio now ships two controls against it. Same-browser
9
+binding is automatic on Composio managed apps: a connection has to be finished in the browser that
10
+started it. Callback identity verification is opt-in per project, and it's the one to reach for on
11
+your own OAuth apps, since it ties activation to your signed-in user rather than the browser.
12
13
### What shipped
14
docs/content/reference/api-reference/connected-accounts/index.mdx
+1
-1
@@ -40,7 +40,7 @@ It has one cost. If a user opens the link in one browser but the provider sends
40
41
### Callback identity verification
42
43
-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`.
43
+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`.
44
45
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.
46
docs/content/reference/v3/api-reference/connected-accounts/index.mdx
-20
@@ -28,26 +28,6 @@ These endpoints use your project API key in the `x-api-key` header.
28
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.
29
</Callout>
30
31
-## OAuth connection security
32
-
33
-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.
34
-
35
-### Same-browser binding
36
-
37
-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.
38
-
39
-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.
40
-
41
-### Callback identity verification
42
-
43
-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`.
44
-
45
-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.
46
-
47
-<Callout type="warning">
48
-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.
49
-</Callout>
50
-
31
## Endpoints
32
33
<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"}]} />