1
+---
2
+title: 'SDKs: `link()` matches `initiate()` for the multi-connection guard'
3
+description: 'TypeScript and Python `connectedAccounts.link()` now refuse to create a second active connection on the same auth config unless `allowMultiple` / `allow_multiple` is set, mirroring `initiate()`. Patch releases.'
4
+date: '2026-04-28'
5
+---
6
+
7
+`composio.connectedAccounts.link()` (TypeScript) and `composio.connected_accounts.link()` (Python) now match the multi-connection guard that `initiate()` already had. With Composio-managed redirectable-OAuth callers being [migrated off `POST /api/v3/connected_accounts` onto `POST /api/v3/connected_accounts/link`](/docs/changelog/2026/04/24/link-auth-migration), the guard moves with them — so the migration doesn't quietly drop the duplicate-connection check.
8
+
9
+<Callout type="warn">
10
+**Behavior change**
11
+
12
+Before: `link()` would happily create a second `ACTIVE` connection for the same `(user_id, auth_config_id)` pair without a follow-up patch.
13
+
14
+After: `link()` first calls `connectedAccounts.list({ userIds, authConfigIds, statuses: ['ACTIVE'] })`. If any active connection exists, `link()` throws `ComposioMultipleConnectedAccountsError` unless the caller passes `allowMultiple: true` (TypeScript) / `allow_multiple=True` (Python).
15
+</Callout>
16
+
17
+### SDK versions (patch releases)
18
+
19
+| Package | Previous | This release |
20
+| ------- | -------- | ------------ |
21
+| TypeScript `@composio/core` | v0.8.0 | **v0.8.1** |
22
+| Python `composio` | v0.12.0 | **v0.12.1** |
23
+
24
+### Migration
25
+
26
+Most callers don't need to do anything — `link()` raised an unrelated error or succeeded by accident in the duplicate-connection case before, and now raises a typed error you can handle. Two scenarios that need attention:
27
+
28
+**1. You intentionally create multiple connections per `(user, auth_config)`** — for example, two Gmail accounts for the same user. Opt in:
29
+
30
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
31
+<Tab value="Python">
32
+```python
33
+connection_request = composio.connected_accounts.link(
34
+ user_id="user_123",
35
+ auth_config_id="ac_xxx",
36
+ alias="work-gmail",
37
+ allow_multiple=True,
38
+)
39
+```
40
+</Tab>
41
+<Tab value="TypeScript">
42
+```typescript
43
+// @noErrors
44
+import { Composio } from '@composio/core';
45
+const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY! });
46
+// ---cut---
47
+const connectionRequest = await composio.connectedAccounts.link(
48
+ 'user_123',
49
+ 'ac_xxx',
50
+ { alias: 'work-gmail', allowMultiple: true },
51
+);
52
+```
53
+</Tab>
54
+</Tabs>
55
+
56
+Pair with a session-level `multiAccount` / `multi_account` config so the agent can disambiguate at execution time. See [Configuring Sessions](/docs/configuring-sessions) for the session shape.
57
+
58
+**2. You're migrating from `initiate()` to `link()`** as part of the [Composio-managed OAuth migration](/docs/changelog/2026/04/24/link-auth-migration). Pass `allow_multiple` / `allowMultiple` through unchanged — same flag name, same default (`False`), same exception (`ComposioMultipleConnectedAccountsError`).
59
+
60
+### Why
61
+
62
+The migration changelog moves callers off `connected_accounts/create` onto `/link`. `initiate()` had `allow_multiple` and the duplicate-connection check; `link()` didn't. Without this fix, every customer who migrates would silently lose the guard and start creating duplicate `ACTIVE` connections on auth configs that were never meant to hold more than one. This release closes that gap.