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): humanize changelog (skill) + correct the complete_auth state machine
Anshu Garg33cfc964f5aa
diff --git a/docs/api-overviews/connected-accounts.mdx b/docs/api-overviews/connected-accounts.mdxindex 59fc9bea5..3dcf3d470 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`. 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`.+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.diff --git a/docs/content/changelog/07-30-26-oauth-connection-binding.mdx b/docs/content/changelog/07-30-26-oauth-connection-binding.mdxindex 34e85838d..950b4d838 100644--- a/docs/content/changelog/07-30-26-oauth-connection-binding.mdx+++ b/docs/content/changelog/07-30-26-oauth-connection-binding.mdx@@ -1,23 +1,24 @@---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: "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."----Composio now stops an OAuth connection from being completed by someone other than the person who-started it. On Composio-managed apps this is enforced automatically, bound to the browser that-started the flow. Any project can also opt into callback identity verification, which ties activation-to the user — the durable way to secure your own OAuth apps.+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.### What shipped-- **Same-browser binding** — for **Composio-managed apps** (default auth configs). Because Composio- owns the OAuth app here, it enforces this automatically: a Connect Link must be completed in the- browser that started it, and a callback from a different browser is rejected. It stays on for every- managed connection, including where identity verification is also enabled. No setup required.+- **Same-browser binding**, for Composio managed apps (default auth configs). Composio owns the OAuth+ app here, so it enforces this for you: a Connect Link has to be completed in the browser that+ started it, and a callback from a different browser is rejected. It stays on for every managed+ connection, including ones where identity verification is also on. Nothing to set up.[Learn more](/reference/api-reference/connected-accounts#same-browser-binding)-- **Callback identity verification** — an opt-in, per-project identity check, and the most reliable- way to secure your **own OAuth apps**. Set a verifier URL, and Composio holds every OAuth connection- in the project — managed and custom alike — until your server confirms the returning user matches- the one it was created for. Enable it in Settings → General.+- **Callback identity verification**, an opt-in check you turn on per project. Set a verifier URL, and+ Composio holds every OAuth connection in the project, managed and custom, until your server confirms+ the returning user matches the one it was created for. It verifies the user rather than the browser,+ so none of the same-browser edge cases apply. Turn it on in Settings → General.[Learn more](/reference/api-reference/connected-accounts#callback-identity-verification)diff --git a/docs/content/reference/api-reference/connected-accounts/index.mdx b/docs/content/reference/api-reference/connected-accounts/index.mdxindex e9684f36a..bf3fd2ddb 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`. 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`.+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.diff --git a/docs/content/reference/v3/api-reference/connected-accounts/index.mdx b/docs/content/reference/v3/api-reference/connected-accounts/index.mdxindex 973a3606d..18e84726a 100644--- a/docs/content/reference/v3/api-reference/connected-accounts/index.mdx+++ b/docs/content/reference/v3/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`. 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`.+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.