@devries-cameron20 / composio Mirror · read-only / commits / 33cfc964f
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 17:15 UTC

docs(auth): humanize changelog (skill) + correct the complete_auth state machine

Changelog: run through good-docs-writing — remove every em-dash, drop the salesy 'most reliable way', plainer confident voice. connected-accounts overview + both index files: correct the completion outcomes. Per completeFromSession, only an identity mismatch fails the connection (FAILED + status_reason IDENTITY_VERIFICATION_FAILED); any other error leaves it pending so the flow can be restarted; the session_uri is consumed either way. The old text read as if the connection always moved to FAILED.

Anshu Garg committed Jul 30, 2026 at 18:33 UTC 33cfc964f5aadc946ae7a91f9e733ee28a584cf8
4 files changed +17 -16
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`. On a mismatch the request returns `400` and the connection moves to `FAILED`. The `session_uri` lasts ten minutes and can be redeemed once; a second redemption 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 `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`.
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
+14 -13
@@ -1,23 +1,24 @@
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: "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."
5 ---
6
7 -Composio now stops an OAuth connection from being completed by someone other than the person who
8 -started it. On Composio-managed apps this is enforced automatically, bound to the browser that
9 -started the flow. Any project can also opt into callback identity verification, which ties activation
10 -to the user — the durable way to secure your own OAuth apps.
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.
12
13 ### What shipped
14
14 -- **Same-browser binding** — for **Composio-managed apps** (default auth configs). Because Composio
15 - owns the OAuth app here, it enforces this automatically: a Connect Link must be completed in the
16 - browser that started it, and a callback from a different browser is rejected. It stays on for every
17 - managed connection, including where identity verification is also enabled. No setup required.
15 +- **Same-browser binding**, for Composio managed apps (default auth configs). Composio owns the OAuth
16 + app here, so it enforces this for you: a Connect Link has to be completed in the browser that
17 + started it, and a callback from a different browser is rejected. It stays on for every managed
18 + connection, including ones where identity verification is also on. Nothing to set up.
19 [Learn more](/reference/api-reference/connected-accounts#same-browser-binding)
19 -- **Callback identity verification** — an opt-in, per-project identity check, and the most reliable
20 - way to secure your **own OAuth apps**. Set a verifier URL, and Composio holds every OAuth connection
21 - in the project — managed and custom alike — until your server confirms the returning user matches
22 - the one it was created for. Enable it in Settings → General.
20 +- **Callback identity verification**, an opt-in check you turn on per project. Set a verifier URL, and
21 + Composio holds every OAuth connection in the project, managed and custom, until your server confirms
22 + the returning user matches the one it was created for. It verifies the user rather than the browser,
23 + so none of the same-browser edge cases apply. Turn it on in Settings → General.
24 [Learn more](/reference/api-reference/connected-accounts#callback-identity-verification)
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`. On a mismatch the request returns `400` and the connection moves to `FAILED`. The `session_uri` lasts ten minutes and can be redeemed once; a second redemption 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 `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
docs/content/reference/v3/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`. On a mismatch the request returns `400` and the connection moves to `FAILED`. The `session_uri` lasts ten minutes and can be redeemed once; a second redemption 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 `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