@devries-cameron20 / composio-1 / commits / a4a4427c6
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(auth): drop same-browser binding from the reference; keep session fixation

Same-browser binding is not enabled, so remove it from the connected-accounts reference and concept map. Keep the OAuth session fixation definition as the rationale for callback identity verification, which is now the single control the section documents. Regenerated both index pages; repointed the concept map to #callback-identity-verification.

Anshu Garg committed Jul 31, 2026 at 13:56 UTC a4a4427c681a640604cb82b74085e72abd4d0627
4 files changed +10 -34
docs/agent/instructions/context.md
+1 -1
@@ -24,7 +24,7 @@ This is your always-on map of Composio's concepts and the canonical page for eac
24 - **Manual auth** — generate Connect Links yourself with `session.authorize()`. → [Manually authenticating users](/docs/authenticating-users/manually-authenticating)
25 - **Managed vs custom auth** — use Composio's managed OAuth apps, or bring your own for branding/scopes. → [Managed vs custom auth](/docs/custom-app-vs-managed-app)
26 - **White-labeling** — remove Composio branding from the auth flow. → [White-labeling authentication](/docs/white-labeling-authentication)
27 -- **OAuth connection security** — two controls against OAuth session fixation, documented in the connected-accounts API overview: same-browser binding (Composio-managed apps only; the `This connection was started from a different browser or device` rejection and the in-app-browser limitation) and callback identity verification (opt-in per project via a verifier URL + `complete_auth`; once set it covers every OAuth connection in the project, managed and custom). This is the section for "connections from the dashboard stopped completing" and "a real `user_id` is now required". → [OAuth connection security](/reference/api-reference/connected-accounts#oauth-connection-security)
27 +- **Callback identity verification** — opt-in per-project defense against OAuth session fixation, documented in the connected-accounts API overview: set a verifier URL and Composio holds each OAuth connection until the developer's server confirms the returning user (`complete_auth`); once set it covers every OAuth connection in the project. This is the section for "connections from the dashboard stopped completing" and "a real `user_id` is now required". → [Callback identity verification](/reference/api-reference/connected-accounts#callback-identity-verification)
28 - **Importing existing connections** — pass in API keys or bearer tokens you already hold. → [Importing existing connections](/docs/importing-existing-connections)
29 - **Multiple accounts per user** — e.g. work and personal Gmail. → [Managing multiple connected accounts](/docs/managing-multiple-connected-accounts)
30 - **Shared connections** — share one connected account across users via an ACL. → [Shared connections](/docs/authenticating-users/shared-connections)
docs/api-overviews/connected-accounts.mdx
+3 -11
@@ -21,21 +21,13 @@ These endpoints use your project API key in the `x-api-key` header.
21 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.
22 </Callout>
23
24 -## OAuth connection security
24 +## Callback identity verification
25
26 -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.
27 -
28 -### Same-browser binding
29 -
30 -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.
31 -
32 -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.
33 -
34 -### Callback identity verification
26 +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. This is OAuth session fixation. Callback identity verification defends against it by confirming the returning user before a connection activates.
27
28 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`.
29
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.
30 +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.
31
32 <Callout type="warning">
33 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.
docs/content/reference/api-reference/connected-accounts/index.mdx
+3 -11
@@ -28,21 +28,13 @@ 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
31 +## Callback identity verification
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
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. This is OAuth session fixation. Callback identity verification defends against it by confirming the returning user before a connection activates.
34
35 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`.
36
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.
37 +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.
38
39 <Callout type="warning">
40 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.
docs/content/reference/v3/api-reference/connected-accounts/index.mdx
+3 -11
@@ -28,21 +28,13 @@ 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
31 +## Callback identity verification
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
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. This is OAuth session fixation. Callback identity verification defends against it by confirming the returning user before a connection activates.
34
35 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`.
36
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.
37 +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.
38
39 <Callout type="warning">
40 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.