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): 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