Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
feat(sdk-py): SEC-339 deprecation warning + typed exception in initiate()
Add ComposioLegacyConnectedAccountsEndpointRetiredError exception class, catch BadRequestError from the retiring path inside initiate() and re-raise as the typed exception, and emit a one-time DeprecationWarning when the response indicates a redirectable OAuth scheme. Update the docstring to flag the cutover dates. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Composio committed
Apr 25, 2026 at 18:12 UTC
61db8296473fb5a7a180016fa3ff7f8e7e117c0b
2 files changed
+96
-6
python/composio/core/models/connected_accounts.py
+80
-6
@@ -4,12 +4,13 @@ import functools
4
import logging
5
import time
6
import typing as t
7
+import warnings
8
9
import typing_extensions as te
10
11
from composio import exceptions
12
from composio.client import HttpClient
12
-from composio_client import omit
13
+from composio_client import BadRequestError, omit
14
from composio.client.types import (
15
connected_account_create_params,
16
connected_account_patch_params,
@@ -22,6 +23,15 @@ from .base import Resource
23
24
logger = logging.getLogger(__name__)
25
26
+# SEC-339: schemes that take the redirectable OAuth path on the legacy
27
+# `POST /api/v3/connected_accounts` endpoint, and so are subject to the
28
+# 2026-05-08 / 2026-07-03 retirement when the auth config is Composio-managed.
29
+_LEGACY_RETIRING_OAUTH_SCHEMES = frozenset({"OAUTH1", "OAUTH2", "DCR_OAUTH"})
30
+
31
+# One-time-per-process guard so long-running services don't spam the deprecation
32
+# warning on every initiate() call.
33
+_legacy_initiate_warning_emitted = False
34
+
35
36
class ConnectionRequest(Resource):
37
"""
@@ -403,7 +413,26 @@ class ConnectedAccounts:
413
a new connected account and returns a connection request.
414
415
Users can then wait for the connection to be established using the
406
- `wait_for_connection` method.
416
+ ``wait_for_connection`` method.
417
+
418
+ .. deprecated::
419
+ For Composio-managed (default) auth configs on redirectable OAuth
420
+ schemes (OAuth1, OAuth2, DCR_OAUTH), the legacy endpoint this
421
+ method wraps is being retired: **2026-05-08** for new
422
+ organizations and **2026-07-03** for all remaining organizations.
423
+ After your org's cutover, this method will raise
424
+ :class:`composio.exceptions.ComposioLegacyConnectedAccountsEndpointRetiredError`
425
+ for that specific combination.
426
+
427
+ Use :meth:`ConnectedAccounts.link` for Composio-managed OAuth — it
428
+ works for every redirectable scheme regardless of whether the
429
+ auth config is Composio-managed or custom, and the return shape
430
+ is the same.
431
+
432
+ Custom auth configs (your own OAuth app) and non-OAuth schemes
433
+ (API key, bearer token, basic auth) are unaffected and continue
434
+ to work on ``initiate()``. See
435
+ https://docs.composio.dev/docs/changelog/2026/04/24
436
437
:param user_id: The user ID to create the connected account for.
438
:param auth_config_id: The auth config ID to create the connected account for.
@@ -437,10 +466,55 @@ class ConnectedAccounts:
466
if alias is not None:
467
connection["alias"] = alias
468
440
- response = self._client.connected_accounts.create(
441
- auth_config={"id": auth_config_id},
442
- connection=t.cast(connected_account_create_params.Connection, connection),
443
- )
469
+ try:
470
+ response = self._client.connected_accounts.create(
471
+ auth_config={"id": auth_config_id},
472
+ connection=t.cast(
473
+ connected_account_create_params.Connection, connection
474
+ ),
475
+ )
476
+ except BadRequestError as error:
477
+ # SEC-339: When the server has flipped this org to the retired
478
+ # path, the legacy endpoint returns 400 with a stable migration
479
+ # message. Surface it as a typed error so callers get an
480
+ # actionable hint instead of a generic BadRequestError.
481
+ message = str(error)
482
+ if (
483
+ "no longer supported" in message
484
+ and "/api/v3/connected_accounts/link" in message
485
+ ):
486
+ raise exceptions.ComposioLegacyConnectedAccountsEndpointRetiredError(
487
+ message
488
+ ) from error
489
+ raise
490
+
491
+ # SEC-339: Warn once per process when a successful initiate() lands
492
+ # on the redirectable-OAuth path. We can't tell from the response
493
+ # alone whether the auth config is Composio-managed (the field that
494
+ # determines whether the cutover applies), so the warning text is
495
+ # conditional in wording — custom-OAuth users can ignore it,
496
+ # Composio-managed-OAuth users see a clear pointer to link() before
497
+ # their org's cutover lands.
498
+ global _legacy_initiate_warning_emitted
499
+ response_auth_scheme = getattr(response.connection_data, "auth_scheme", None)
500
+ if (
501
+ not _legacy_initiate_warning_emitted
502
+ and isinstance(response_auth_scheme, str)
503
+ and response_auth_scheme in _LEGACY_RETIRING_OAUTH_SCHEMES
504
+ ):
505
+ _legacy_initiate_warning_emitted = True
506
+ warnings.warn(
507
+ "composio.connected_accounts.initiate() will stop working "
508
+ "for Composio-managed OAuth auth configs on 2026-05-08 (new "
509
+ "orgs) and 2026-07-03 (all orgs). If this auth config is "
510
+ "Composio-managed, switch to "
511
+ "composio.connected_accounts.link() before then. Custom "
512
+ "auth configs are unaffected. See "
513
+ "https://docs.composio.dev/docs/changelog/2026/04/24",
514
+ DeprecationWarning,
515
+ stacklevel=2,
516
+ )
517
+
518
return ConnectionRequest(
519
id=response.id,
520
status=response.connection_data.val.status,
python/composio/exceptions.py
+16
@@ -315,6 +315,22 @@ class ComposioMultipleConnectedAccountsError(ConnectedAccountError):
315
pass
316
317
318
+class ComposioLegacyConnectedAccountsEndpointRetiredError(ConnectedAccountError):
319
+ """Raised by ``composio.connected_accounts.initiate()`` when the legacy
320
+ ``POST /api/v3/connected_accounts`` endpoint rejects a Composio-managed
321
+ OAuth (OAuth1, OAuth2, DCR_OAUTH) auth-config request.
322
+
323
+ Cutover dates: 2026-05-08 (new orgs), 2026-07-03 (all remaining orgs).
324
+ Migrate to ``composio.connected_accounts.link()`` — same return shape,
325
+ works for every redirectable scheme regardless of whether the auth
326
+ config is Composio-managed or custom.
327
+
328
+ See: https://docs.composio.dev/docs/changelog/2026/04/24
329
+ """
330
+
331
+ pass
332
+
333
+
334
class ErrorProcessingToolExecutionRequest(PluginError):
335
pass
336