Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
mdx 61 lines 3.34 KB
Raw
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), 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 checking for an existing `ACTIVE` connection first.
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 import { Composio } from '@composio/core';
44 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY! });
45 // ---cut---
46 const connectionRequest = await composio.connectedAccounts.link(
47 'user_123',
48 'ac_xxx',
49 { alias: 'work-gmail', allowMultiple: true },
50 );
51 ```
52 </Tab>
53 </Tabs>
54
55 Pair with a session-level `multiAccount` / `multi_account` config so the agent can disambiguate at execution time. See [Managing multiple connected accounts](/docs/authentication/managing-multiple-connected-accounts) for the session shape.
56
57 **2. You're migrating from `initiate()` to `link()`** as part of the [Composio-managed OAuth migration](/docs/changelog/2026/04/24). Pass `allow_multiple` / `allowMultiple` through unchanged — same flag name, same default (`False`), same exception (`ComposioMultipleConnectedAccountsError`).
58
59 ### Why
60
61 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.