Skip to content

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): generate the connected-accounts index (section on v3.1 and v3)

Anshu Gargcb5dc6247873
diff --git a/docs/content/reference/v3/api-reference/connected-accounts/index.mdx b/docs/content/reference/v3/api-reference/connected-accounts/index.mdx
index 33d2d9ddf..ba7390aba 100644
--- a/docs/content/reference/v3/api-reference/connected-accounts/index.mdx
+++ b/docs/content/reference/v3/api-reference/connected-accounts/index.mdx
@@ -28,6 +28,26 @@ 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 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.
+
+<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"}]} />