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): add migrating-initiate-to-link.mdx guide
Composio51631c9164c0
diff --git a/docs/content/docs/auth-configuration/meta.json b/docs/content/docs/auth-configuration/meta.jsonindex a84f4297b..dee687b3f 100644--- a/docs/content/docs/auth-configuration/meta.json+++ b/docs/content/docs/auth-configuration/meta.json@@ -6,6 +6,7 @@"white-labeling","programmatic-auth-configs","custom-auth-params",- "connected-accounts"+ "connected-accounts",+ "migrating-initiate-to-link"]}diff --git a/docs/content/docs/auth-configuration/migrating-initiate-to-link.mdx b/docs/content/docs/auth-configuration/migrating-initiate-to-link.mdxnew file mode 100644index 000000000..1361fb754--- /dev/null+++ b/docs/content/docs/auth-configuration/migrating-initiate-to-link.mdx@@ -0,0 +1,213 @@+---+title: Migrating from initiate() to link()+description: Move Composio-managed OAuth flows off the legacy POST /api/v3/connected_accounts endpoint and onto link() before the 2026-05-08 / 2026-07-03 cutover.+---++`composio.connected_accounts.initiate()` (Python) and `composio.connectedAccounts.initiate()` (TypeScript) wrap `POST /api/v3/connected_accounts`. That endpoint is being retired for **Composio-managed auth configs on redirectable OAuth schemes** (OAuth1, OAuth2, DCR_OAUTH):++- **2026-05-08, 00:00 UTC** — organizations created on or after this date are blocked.+- **2026-07-03, 00:00 UTC** — all remaining organizations are blocked.++After your org's cutover, calling `initiate()` for the affected combination raises `ComposioLegacyConnectedAccountsEndpointRetiredError` (TS) / `composio.exceptions.ComposioLegacyConnectedAccountsEndpointRetiredError` (Python). The replacement is `link()` — same return shape, same `redirectUrl` / `redirect_url`, same `waitForConnection()` / `wait_for_connection()` helper.++<Callout type="info">+**Who this affects:** developers using a Composio-managed (default) auth config on OAuth1, OAuth2, or DCR_OAUTH. If you brought your own OAuth client credentials (custom auth config) or use a non-OAuth scheme (API key, bearer, basic), your `initiate()` calls keep working — no migration needed.+</Callout>++## Why++When a connection is initiated through a default (Composio-managed) auth config, a Composio-owned OAuth application is acting on behalf of your integration. The end user should explicitly understand and acknowledge, at the moment of connection, that they are granting a third-party application access to their account on the external service. The `link()` flow enforces that consent step; the legacy `initiate()` path could bypass it when credentials were passed in directly. Concentrating Composio-managed OAuth on `link()` aligns the user experience with that consent guarantee.++## Migration at a glance++The signatures are the same shape — only the method name changes for the OAuth case.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+**Before:**++```python+connection_request = composio.connected_accounts.initiate(+ user_id="user_123",+ auth_config_id="ac_abc",+)+print(connection_request.redirect_url)+connected_account = connection_request.wait_for_connection()+```++**After:**++```python+connection_request = composio.connected_accounts.link(+ user_id="user_123",+ auth_config_id="ac_abc",+)+print(connection_request.redirect_url)+connected_account = connection_request.wait_for_connection()+```+</Tab>+<Tab value="TypeScript">+**Before:**++```typescript+const connectionRequest = await composio.connectedAccounts.initiate(+ 'user_123',+ 'ac_abc'+);+console.log(connectionRequest.redirectUrl);+const connectedAccount = await connectionRequest.waitForConnection();+```++**After:**++```typescript+const connectionRequest = await composio.connectedAccounts.link(+ 'user_123',+ 'ac_abc'+);+console.log(connectionRequest.redirectUrl);+const connectedAccount = await connectionRequest.waitForConnection();+```+</Tab>+</Tabs>++`callback_url` / `callbackUrl` and `alias` work the same way on both methods.++## What changes between the two methods++| Concern | `initiate()` | `link()` |+|---|---|---|+| Underlying endpoint | `POST /api/v3/connected_accounts` | `POST /api/v3/connected_accounts/link` |+| Return shape | `ConnectionRequest` with `id`, `redirect_url`, `wait_for_connection()` | Same |+| `callback_url` / `callbackUrl` | ✓ | ✓ |+| `alias` | ✓ | ✓ |+| Pre-filled connection state (`config`) | ✓ — for non-OAuth schemes | Not needed — OAuth uses redirect; non-OAuth users keep `initiate()` |+| `allow_multiple` / `allowMultiple` guard | ✓ | ✗ — handle client-side (see below) |+| Subject to SEC-339 retirement (Composio-managed OAuth) | Yes | No |++## Handling `allow_multiple`++`initiate()` rejects a request if an active connected account already exists for `(user_id, auth_config_id)` unless you pass `allow_multiple=True`. `link()` does not have this guard — it always creates a new connection.++If you depend on the duplicate-rejection behavior, replicate it client-side:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+from composio import exceptions++existing = composio.connected_accounts.list(+ user_ids=["user_123"],+ auth_config_ids=["ac_abc"],+ statuses=["ACTIVE"],+)+if existing.items and not allow_multiple:+ raise exceptions.ComposioMultipleConnectedAccountsError(+ f"Active connection already exists for user_123 in ac_abc"+ )++connection_request = composio.connected_accounts.link(+ user_id="user_123",+ auth_config_id="ac_abc",+)+```+</Tab>+<Tab value="TypeScript">+```typescript+import { ComposioMultipleConnectedAccountsError, ConnectedAccountStatuses } from '@composio/core';++const existing = await composio.connectedAccounts.list({+ userIds: ['user_123'],+ authConfigIds: ['ac_abc'],+ statuses: [ConnectedAccountStatuses.ACTIVE],+});+if (existing.items.length > 0 && !allowMultiple) {+ throw new ComposioMultipleConnectedAccountsError(+ 'Active connection already exists for user_123 in ac_abc'+ );+}++const connectionRequest = await composio.connectedAccounts.link(+ 'user_123',+ 'ac_abc'+);+```+</Tab>+</Tabs>++## How to know which auth config is which++If you maintain a mix of Composio-managed and custom auth configs and aren't sure which path to take per call, look at the auth config record. The dashboard shows whether each config is "Default (Composio-managed)" or "Custom". Programmatically, the auth config retrieve response includes an `is_composio_managed` (Python) / `isComposioManaged` (TS) boolean. Route the call based on that field:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+<Tab value="Python">+```python+auth_config = composio.auth_configs.get("ac_abc")++if auth_config.is_composio_managed:+ request = composio.connected_accounts.link(+ user_id="user_123",+ auth_config_id="ac_abc",+ )+else:+ request = composio.connected_accounts.initiate(+ user_id="user_123",+ auth_config_id="ac_abc",+ )+```+</Tab>+<Tab value="TypeScript">+```typescript+const authConfig = await composio.authConfigs.get('ac_abc');++const request = authConfig.isComposioManaged+ ? await composio.connectedAccounts.link('user_123', 'ac_abc')+ : await composio.connectedAccounts.initiate('user_123', 'ac_abc');+```+</Tab>+</Tabs>++For most integrations the auth config is hard-coded per integration, so you'll know up front which path to use and can drop the branching.++## Detecting the deprecation early++Two server-side signals fire ahead of the cutover so SDK and direct API clients can react before they hit a 400:++1. **SDK warning.** When the up-to-date Composio SDK detects a successful `initiate()` on a redirectable OAuth scheme, it logs a one-time `DeprecationWarning` (Python) / `console.warn` (TS) pointing to this guide. Install or upgrade to the latest SDK version to pick it up.+2. **HTTP `Deprecation` and `Sunset` headers** ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)). Successful responses on the retiring path carry:++ ```+ Deprecation: true+ Sunset: Fri, 08 May 2026 00:00:00 GMT+ Link: <https://docs.composio.dev/docs/changelog/2026/04/24>; rel="deprecation"+ ```++ Direct HTTP callers can detect these in their response interceptor and surface a deprecation notice in their own logs / dashboards.++## After the cutover++Once your org is past its cutover date, the legacy endpoint returns `400 BadRequest` (error code `600`) for Composio-managed OAuth. The SDK surfaces this as `ComposioLegacyConnectedAccountsEndpointRetiredError` — catch it where you call `initiate()` to keep your error logs readable, then migrate the call to `link()`.++```python+from composio import exceptions++try:+ request = composio.connected_accounts.initiate(+ user_id="user_123",+ auth_config_id="ac_abc",+ )+except exceptions.ComposioLegacyConnectedAccountsEndpointRetiredError:+ request = composio.connected_accounts.link(+ user_id="user_123",+ auth_config_id="ac_abc",+ )+```++This is meant as a safety net during migration — the long-term answer is to switch the call site to `link()` outright.++## Related++- [Connected accounts → Multiple accounts](/docs/auth-configuration/connected-accounts#multiple-accounts) — using `link()` for multi-account flows+- [Authenticating tools → Hosted Authentication](/docs/tools-direct/authenticating-tools#hosted-authentication-connect-link) — the canonical `link()` flow+- [API errors → Error 600](/reference/errors#error-600) — the 400 response shape+- [Changelog: Link Auth Migration](/docs/changelog/2026/04/24) — the announcement