Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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. |