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) |
85
+| `allow_multiple` / `allowMultiple` | ✓ — guards against duplicates | Not applicable — `link()` always creates a new connection by design |
86
| Affected by the 2026-05-08 / 2026-07-03 retirement (Composio-managed OAuth) | Yes | No |
87
88
-## Handling `allow_multiple`
88
+## `allow_multiple` is no longer needed
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.
90
+`initiate()` accepts an `allow_multiple` / `allowMultiple` flag that defaults to `False` — calling it twice for the same `(user_id, auth_config_id)` raises an error unless you opt in. `link()` does not need this flag and does not accept it: every call creates a fresh connection request, which is the right default for the common case where a user connects more than one account for the same toolkit (for example, a personal and a work Google account).
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>
92
+If your application logic should keep a user to at most one active connection per auth config, enforce that in your own UI rather than at the SDK layer — for example, list the user's active connections with `composio.connected_accounts.list({...})` before showing the Connect button and skip the call to `link()` when one already exists.
93
94
## How to know which auth config is which
95
125
126
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.
127
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
-
128
## Related
129
130
- [Connected accounts → Multiple accounts](/docs/auth-configuration/connected-accounts#multiple-accounts) — using `link()` for multi-account flows