@devries-cameron20 / composio Mirror · read-only / commits / 51631c916
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, 22:15 UTC

docs(auth): add migrating-initiate-to-link.mdx guide

Dedicated migration guide for moving Composio-managed OAuth flows off initiate() and onto link(). Covers: - Side-by-side before/after for both Python and TypeScript - Differences in supported options (allow_multiple, config pre-fill) - Replacement pattern for the duplicate-rejection guard - is_composio_managed routing recipe for mixed integrations - Detection signals: SDK warning + RFC 8594 Deprecation/Sunset headers - After-cutover error-handling example Wired into the Authentication sidebar via meta.json. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Composio committed Apr 25, 2026 at 18:12 UTC 51631c9164c06facf31cd869e4be20a0160667a0
2 files changed +215 -1
docs/content/docs/auth-configuration/meta.json
+2 -1
@@ -6,6 +6,7 @@
6 "white-labeling",
7 "programmatic-auth-configs",
8 "custom-auth-params",
9 - "connected-accounts"
9 + "connected-accounts",
10 + "migrating-initiate-to-link"
11 ]
12 }
docs/content/docs/auth-configuration/migrating-initiate-to-link.mdx new
+213
@@ -0,0 +1,213 @@
1 +---
2 +title: Migrating from initiate() to link()
3 +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.
4 +---
5 +
6 +`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):
7 +
8 +- **2026-05-08, 00:00 UTC** — organizations created on or after this date are blocked.
9 +- **2026-07-03, 00:00 UTC** — all remaining organizations are blocked.
10 +
11 +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.
12 +
13 +<Callout type="info">
14 +**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.
15 +</Callout>
16 +
17 +## Why
18 +
19 +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.
20 +
21 +## Migration at a glance
22 +
23 +The signatures are the same shape — only the method name changes for the OAuth case.
24 +
25 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
26 +<Tab value="Python">
27 +**Before:**
28 +
29 +```python
30 +connection_request = composio.connected_accounts.initiate(
31 + user_id="user_123",
32 + auth_config_id="ac_abc",
33 +)
34 +print(connection_request.redirect_url)
35 +connected_account = connection_request.wait_for_connection()
36 +```
37 +
38 +**After:**
39 +
40 +```python
41 +connection_request = composio.connected_accounts.link(
42 + user_id="user_123",
43 + auth_config_id="ac_abc",
44 +)
45 +print(connection_request.redirect_url)
46 +connected_account = connection_request.wait_for_connection()
47 +```
48 +</Tab>
49 +<Tab value="TypeScript">
50 +**Before:**
51 +
52 +```typescript
53 +const connectionRequest = await composio.connectedAccounts.initiate(
54 + 'user_123',
55 + 'ac_abc'
56 +);
57 +console.log(connectionRequest.redirectUrl);
58 +const connectedAccount = await connectionRequest.waitForConnection();
59 +```
60 +
61 +**After:**
62 +
63 +```typescript
64 +const connectionRequest = await composio.connectedAccounts.link(
65 + 'user_123',
66 + 'ac_abc'
67 +);
68 +console.log(connectionRequest.redirectUrl);
69 +const connectedAccount = await connectionRequest.waitForConnection();
70 +```
71 +</Tab>
72 +</Tabs>
73 +
74 +`callback_url` / `callbackUrl` and `alias` work the same way on both methods.
75 +
76 +## What changes between the two methods
77 +
78 +| Concern | `initiate()` | `link()` |
79 +|---|---|---|
80 +| Underlying endpoint | `POST /api/v3/connected_accounts` | `POST /api/v3/connected_accounts/link` |
81 +| Return shape | `ConnectionRequest` with `id`, `redirect_url`, `wait_for_connection()` | Same |
82 +| `callback_url` / `callbackUrl` | ✓ | ✓ |
83 +| `alias` | ✓ | ✓ |
84 +| Pre-filled connection state (`config`) | ✓ — for non-OAuth schemes | Not needed — OAuth uses redirect; non-OAuth users keep `initiate()` |
85 +| `allow_multiple` / `allowMultiple` guard | ✓ | ✗ — handle client-side (see below) |
86 +| Subject to SEC-339 retirement (Composio-managed OAuth) | Yes | No |
87 +
88 +## Handling `allow_multiple`
89 +
90 +`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.
91 +
92 +If you depend on the duplicate-rejection behavior, replicate it client-side:
93 +
94 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
95 +<Tab value="Python">
96 +```python
97 +from composio import exceptions
98 +
99 +existing = composio.connected_accounts.list(
100 + user_ids=["user_123"],
101 + auth_config_ids=["ac_abc"],
102 + statuses=["ACTIVE"],
103 +)
104 +if existing.items and not allow_multiple:
105 + raise exceptions.ComposioMultipleConnectedAccountsError(
106 + f"Active connection already exists for user_123 in ac_abc"
107 + )
108 +
109 +connection_request = composio.connected_accounts.link(
110 + user_id="user_123",
111 + auth_config_id="ac_abc",
112 +)
113 +```
114 +</Tab>
115 +<Tab value="TypeScript">
116 +```typescript
117 +import { ComposioMultipleConnectedAccountsError, ConnectedAccountStatuses } from '@composio/core';
118 +
119 +const existing = await composio.connectedAccounts.list({
120 + userIds: ['user_123'],
121 + authConfigIds: ['ac_abc'],
122 + statuses: [ConnectedAccountStatuses.ACTIVE],
123 +});
124 +if (existing.items.length > 0 && !allowMultiple) {
125 + throw new ComposioMultipleConnectedAccountsError(
126 + 'Active connection already exists for user_123 in ac_abc'
127 + );
128 +}
129 +
130 +const connectionRequest = await composio.connectedAccounts.link(
131 + 'user_123',
132 + 'ac_abc'
133 +);
134 +```
135 +</Tab>
136 +</Tabs>
137 +
138 +## How to know which auth config is which
139 +
140 +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:
141 +
142 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
143 +<Tab value="Python">
144 +```python
145 +auth_config = composio.auth_configs.get("ac_abc")
146 +
147 +if auth_config.is_composio_managed:
148 + request = composio.connected_accounts.link(
149 + user_id="user_123",
150 + auth_config_id="ac_abc",
151 + )
152 +else:
153 + request = composio.connected_accounts.initiate(
154 + user_id="user_123",
155 + auth_config_id="ac_abc",
156 + )
157 +```
158 +</Tab>
159 +<Tab value="TypeScript">
160 +```typescript
161 +const authConfig = await composio.authConfigs.get('ac_abc');
162 +
163 +const request = authConfig.isComposioManaged
164 + ? await composio.connectedAccounts.link('user_123', 'ac_abc')
165 + : await composio.connectedAccounts.initiate('user_123', 'ac_abc');
166 +```
167 +</Tab>
168 +</Tabs>
169 +
170 +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.
171 +
172 +## Detecting the deprecation early
173 +
174 +Two server-side signals fire ahead of the cutover so SDK and direct API clients can react before they hit a 400:
175 +
176 +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.
177 +2. **HTTP `Deprecation` and `Sunset` headers** ([RFC 8594](https://www.rfc-editor.org/rfc/rfc8594)). Successful responses on the retiring path carry:
178 +
179 + ```
180 + Deprecation: true
181 + Sunset: Fri, 08 May 2026 00:00:00 GMT
182 + Link: <https://docs.composio.dev/docs/changelog/2026/04/24>; rel="deprecation"
183 + ```
184 +
185 + Direct HTTP callers can detect these in their response interceptor and surface a deprecation notice in their own logs / dashboards.
186 +
187 +## After the cutover
188 +
189 +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()`.
190 +
191 +```python
192 +from composio import exceptions
193 +
194 +try:
195 + request = composio.connected_accounts.initiate(
196 + user_id="user_123",
197 + auth_config_id="ac_abc",
198 + )
199 +except exceptions.ComposioLegacyConnectedAccountsEndpointRetiredError:
200 + request = composio.connected_accounts.link(
201 + user_id="user_123",
202 + auth_config_id="ac_abc",
203 + )
204 +```
205 +
206 +This is meant as a safety net during migration — the long-term answer is to switch the call site to `link()` outright.
207 +
208 +## Related
209 +
210 +- [Connected accounts → Multiple accounts](/docs/auth-configuration/connected-accounts#multiple-accounts) — using `link()` for multi-account flows
211 +- [Authenticating tools → Hosted Authentication](/docs/tools-direct/authenticating-tools#hosted-authentication-connect-link) — the canonical `link()` flow
212 +- [API errors → Error 600](/reference/errors#error-600) — the 400 response shape
213 +- [Changelog: Link Auth Migration](/docs/changelog/2026/04/24) — the announcement