@devries-cameron20 / composio Mirror · read-only / commits / 159ab2eac
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 22:15 UTC

docs(auth): address review on migrating-initiate-to-link

- Reframe `allow_multiple` from a 'replicate client-side' migration burden into a positive note: link() always creates a new connection by design (right default for multi-account UX), and per-user uniqueness belongs in the application UI rather than the SDK layer. Drop the duplicate-rejection code example. - Drop the 'Detecting the deprecation early' and 'After the cutover' sections per review feedback. Customers who land on the page already know they need to migrate; the page can stay focused on the migration itself rather than detection / fallback patterns. - Update the comparison table cell to match the new framing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Composio committed May 4, 2026 at 11:01 UTC 159ab2eacce94cb9df03b4bc38dc3de6ec89b5c6
1 file changed +4 -84
docs/content/docs/auth-configuration/migrating-initiate-to-link.mdx
+4 -84
@@ -82,58 +82,14 @@ const connectedAccount = await connectionRequest.waitForConnection();
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
@@ -169,42 +125,6 @@ const request = authConfig.isComposioManaged
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