Skip to content

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

docs(py): sanitize public docstrings — remove internal references

venkat82d27eecce204c
diff --git a/python/composio/core/models/connected_accounts.py b/python/composio/core/models/connected_accounts.py
index 2efeaae6e..e76158522 100644
--- a/python/composio/core/models/connected_accounts.py
+++ b/python/composio/core/models/connected_accounts.py
@@ -578,14 +578,14 @@ class ConnectedAccounts:
``ACTIVE`` connection on this auth config. Pair with ``alias`` and a
session-level ``multi_account`` config to disambiguate at execution time.
:param account_type: Sharing model for the new connection. ``PRIVATE``
- (default) is usable only by the owning ``user_id``. ``SHARED`` is
- reachable from a tool-router session by other users in the project,
- but only when explicitly pinned and only when the requesting
- ``user_id`` passes the connection's ACL. Set at create time only.
- :param acl_config_for_shared: Per-user ACL for SHARED connections. Only
- valid when ``account_type == 'SHARED'`` — the backend rejects ACL
- on a PRIVATE connection with ``ComposioAclOnlyForSharedError``
- (400). Pass an ``ACLConfigForShared`` dict with any combination of
+ (default) is usable only by the owning ``user_id``. ``SHARED`` can
+ be used by other ``user_id``s — but only when the connection is
+ explicitly pinned in a tool-router session's config and only when
+ the requesting ``user_id`` passes the connection's ACL.
+ :param acl_config_for_shared: Per-user ACL for SHARED connections.
+ Only valid when ``account_type == 'SHARED'``; raises
+ ``ComposioAclOnlyForSharedError`` on a PRIVATE connection. Pass
+ an ``ACLConfigForShared`` dict with any combination of
``allow_all_users``, ``allowed_user_ids``, ``not_allowed_user_ids``.
Omit to keep deny-by-default (only the creator can use).
:return: Connection request object.
@@ -652,9 +652,9 @@ class ConnectedAccounts:
),
)
except BadRequestError as error:
- # Backend rejects ACL on PRIVATE rows with 400 +
- # ``ConnectedAccount_AclOnlyForShared``. Surface it as a typed
- # error so callers can ``except`` instead of grepping messages.
+ # The server rejects ACL on PRIVATE connections — surface that
+ # as a typed error so callers can ``except`` instead of grepping
+ # messages.
message = str(error)
if "acl_config_for_shared is only valid on SHARED" in message:
raise exceptions.ComposioAclOnlyForSharedError(message) from error
@@ -678,53 +678,27 @@ class ConnectedAccounts:
"""
Update the per-user ACL on a SHARED connected account.
- Only meaningful for SHARED connections — the backend rejects ACL
- writes on PRIVATE rows with ``ComposioAclOnlyForSharedError`` (400).
- Auth gate is creator-or-API-key (a non-creator project member
- updating an alias on a SHARED row still works via :meth:`update`,
- but ACL writes do not).
-
- PATCH semantics: omit a parameter to leave it unchanged; pass an
- empty list to clear an allow/deny list. At least one parameter must
- be provided — calling with all three as ``None`` raises
- :class:`composio.exceptions.ValidationError`.
-
- Resolution rule (deny wins):
- 1. requesting user_id in ``not_allowed_user_ids`` → DENY
- 2. ``allow_all_users == True`` → ALLOW
- 3. requesting user_id in ``allowed_user_ids`` → ALLOW
- 4. otherwise → DENY
+ Only valid on SHARED connections; raises
+ ``ComposioAclOnlyForSharedError`` on a PRIVATE connection. Omit a
+ parameter to leave it unchanged; pass an empty list to clear an
+ allow/deny list. At least one parameter must be provided.
:param nanoid: The connected account ID (``ca_xxx``).
- :param allow_all_users: Wildcard "any user_id in the project" allow.
- :param allowed_user_ids: Explicit allow list. Pass ``[]`` to clear.
+ :param allow_all_users: When True, any ``user_id`` may use this
+ SHARED connection (subject to the deny list).
+ :param allowed_user_ids: Explicit list of allowed ``user_id`` strings.
+ Pass ``[]`` to clear.
:param not_allowed_user_ids: Explicit deny list (wins over allow on
conflict). Pass ``[]`` to clear — note that clearing the deny
list silently re-grants access to previously-blocked users.
- :return: PATCH response (``id``, ``status``, ``success``). To read
- back the updated ``acl_config_for_shared`` block, call
- :meth:`get` after this returns.
-
- Example::
-
- # Open access to everyone in the project
- composio.connected_accounts.update_acl('ca_abc', allow_all_users=True)
+ :return: Response with ``id``, ``status``, and ``success``.
- # Everyone except a specific user
+ Example:
composio.connected_accounts.update_acl(
'ca_abc',
allow_all_users=True,
not_allowed_user_ids=['user_bob'],
)
-
- # Targeted allow
- composio.connected_accounts.update_acl(
- 'ca_abc',
- allowed_user_ids=['user_alice', 'user_bob'],
- )
-
- # Revoke a previously-granted allow list (back to deny-by-default)
- composio.connected_accounts.update_acl('ca_abc', allowed_user_ids=[])
"""
if (
allow_all_users is None
diff --git a/python/composio/core/models/tool_router_session.py b/python/composio/core/models/tool_router_session.py
index d9fc3a442..223524b41 100644
--- a/python/composio/core/models/tool_router_session.py
+++ b/python/composio/core/models/tool_router_session.py
@@ -552,13 +552,12 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
:param alias: Human-readable alias for the connection. Must be unique
per userId and toolkit within the project.
:param account_type: Sharing model for the new connection. ``PRIVATE``
- (default) is usable only by the owning user. ``SHARED`` lets other
- users in the project use the connection when pinned. Set at create
- time only.
- :param acl_config_for_shared: Per-user ACL for SHARED connections. Only
- valid when ``account_type == 'SHARED'`` — the backend rejects ACL
- on a PRIVATE connection with ``ComposioAclOnlyForSharedError``
- (400).
+ (default) is usable only by the owning ``user_id``. ``SHARED`` can
+ be used by other ``user_id``s when the connection is pinned in a
+ tool-router session and the requesting user passes its ACL.
+ :param acl_config_for_shared: Per-user ACL for SHARED connections.
+ Only valid when ``account_type == 'SHARED'``; raises
+ ``ComposioAclOnlyForSharedError`` on a PRIVATE connection.
"""
try:
response = self._client.tool_router.session.link(
@@ -572,8 +571,8 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
),
)
except BadRequestError as error:
- # Mirrors the mapper on ``composio.connected_accounts.link()`` —
- # the same backend handler returns ``AclOnlyForShared`` here.
+ # The server rejects ACL on PRIVATE connections — surface that
+ # as a typed error mirroring ``composio.connected_accounts.link()``.
message = str(error)
if "acl_config_for_shared is only valid on SHARED" in message:
raise exceptions.ComposioAclOnlyForSharedError(message) from error
diff --git a/python/composio/exceptions.py b/python/composio/exceptions.py
index 0ba1b676f..9e2e974cc 100644
--- a/python/composio/exceptions.py
+++ b/python/composio/exceptions.py
@@ -334,12 +334,8 @@ class ComposioLegacyConnectedAccountsEndpointRetiredError(ConnectedAccountError)
class ComposioAclOnlyForSharedError(ConnectedAccountError):
"""Raised when ACL fields (``allow_all_users``, ``allowed_user_ids``,
``not_allowed_user_ids``) are sent on a ``PRIVATE`` connection — at
- create time or via PATCH.
-
- ACL is only meaningful for ``SHARED`` connections; the matching layer
- never reads it for PRIVATE. Backend rejects with 400 +
- ``ConnectedAccount_AclOnlyForShared`` rather than silently ignoring the
- ACL block, so developer misconfiguration surfaces loudly.
+ create time or via PATCH. ACL is only meaningful for ``SHARED``
+ connections.
Fix: set ``account_type='SHARED'`` at create time, or omit the ACL
fields when creating/updating a PRIVATE connection.
@@ -353,17 +349,14 @@ class ComposioSharedAccessDeniedError(ConnectedAccountError):
account but the requesting ``user_id`` is not allowed by the
connection's ACL.
- Surfaces from the matching layer when a SHARED connection is reached
- directly (e.g. via ``composio.tools.execute(slug, connected_account_id=...)``)
- without going through a tool-router session that already pre-flighted
- the ACL at session-create time.
+ Surfaces when a SHARED connection is reached directly (e.g. via
+ ``composio.tools.execute(slug, connected_account_id=...)``) without
+ going through a tool-router session.
Fix: ask the connection's creator to grant access via
``composio.connected_accounts.update_acl()`` — set ``allow_all_users``,
add the ``user_id`` to ``allowed_user_ids``, or remove it from
``not_allowed_user_ids``.
-
- Backend response: 403 with code ``ConnectedAccount_SharedAccessDenied``.
"""
pass
@@ -372,15 +365,12 @@ class ComposioSharedAccessDeniedError(ConnectedAccountError):
class ComposioSharedConnectionNotAccessibleError(ConnectedAccountError):
"""Raised by tool-router session create / PATCH when the session's
``user_id`` cannot use a pinned SHARED connection — caught at
- session-create time so the session never enters a state that 4xxs
+ session-create time so the session never enters a state that fails
mid-execution.
Fix: grant the session user access via
``composio.connected_accounts.update_acl()`` on the pinned connection,
or pin a different connection the user can use.
-
- Backend response: 400 with code
- ``ToolRouterV2_SharedConnectionNotAccessible``.
"""
pass
diff --git a/python/tests/test_connected_accounts.py b/python/tests/test_connected_accounts.py
index 3993f9a39..4e789e66d 100644
--- a/python/tests/test_connected_accounts.py
+++ b/python/tests/test_connected_accounts.py
@@ -543,11 +543,8 @@ def _make_bad_request_error(message: str):
class TestConnectedAccountsAcl:
- """Tests for accountType + per-user ACL surfacing (Hermes #9860, #9902).
-
- Mirrors the 12 behaviour tests in
- ``ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts``.
- """
+ """Tests for ``account_type`` + per-user ACL surfacing on ``link()``
+ and ``update_acl()``."""
@pytest.fixture
def mock_client(self):