Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs(shared-connections): align with final SDK surface + add list filter section
venkat821292bc21496d
diff --git a/docs/content/docs/auth-configuration/shared-connections.mdx b/docs/content/docs/auth-configuration/shared-connections.mdxindex 02c21d128..c2f8caedd 100644--- a/docs/content/docs/auth-configuration/shared-connections.mdx+++ b/docs/content/docs/auth-configuration/shared-connections.mdx@@ -6,7 +6,7 @@ llmGuardrails: "direct-execution"---<Callout type="warn">-Shared Connections APIs are experimental and may change in future releases. All new fields are nested under an `experimental` block on the wire, and the SDK methods that operate on them (`experimental_updateAcl`, `composio.experimental.update_acl`) live under an experimental namespace. The code samples below show the experimental shape — pin a specific SDK version if you depend on the current contract.+Shared Connections APIs are experimental and may change in future releases. All new fields are nested under an `experimental` block on the wire, and the SDK methods that operate on them live under the `composio.experimental` namespace (`composio.experimental.update_acl` in Python, `composio.experimental.updateAcl` in TypeScript). The code samples below show the experimental shape — pin a specific SDK version if you depend on the current contract.</Callout><Callout type="info">@@ -156,22 +156,22 @@ composio.experimental.update_acl(<Tab value="TypeScript">```typescript// @noErrors-import { Composio, experimental_updateAcl } from '@composio/core';+import { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---// Open access to everyone.-await experimental_updateAcl(composio, "ca_gmail_shared", {+await composio.experimental.updateAcl("ca_gmail_shared", {allowAllUsers: true,});// Add a targeted allow list (without touching the wildcard or deny list).-await experimental_updateAcl(composio, "ca_gmail_shared", {+await composio.experimental.updateAcl("ca_gmail_shared", {allowedUserIds: ["user_alice", "user_bob"],});// Revoke the allow list — only the creator can use it again// (unless allowAllUsers is true).-await experimental_updateAcl(composio, "ca_gmail_shared", {+await composio.experimental.updateAcl("ca_gmail_shared", {allowedUserIds: [],});```@@ -262,6 +262,56 @@ const result = await composio.tools.execute("GMAIL_SEND_EMAIL", {If `user_alice` isn't permitted by the connection's ACL, the call raises `ComposioSharedAccessDeniedError`.+## Listing SHARED connections++By default `list()` returns **PRIVATE only** — shared accounts must be requested explicitly. Pass an `account_type` (Python) / `accountType` (TypeScript) filter to scope the query.++| Value | Returns |+|---|---|+| `'PRIVATE'` *(default when omitted)* | Only PRIVATE connections |+| `'SHARED'` | Only SHARED connections |+| `'ALL'` | PRIVATE + SHARED |++The filter is a flat query param on the wire (`?account_type=...`), so it stays flat in both SDKs — unlike the create/update surfaces which nest under `experimental`.++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+# List every SHARED connection the caller has visibility into.+shared = composio.connected_accounts.list(account_type="SHARED")++for item in shared.items:+ print(item.id, item.toolkit.slug)++# Scope to a single user's SHARED connections.+shared_for_alice = composio.connected_accounts.list(+ account_type="SHARED",+ user_ids=["user_alice"],+)+```+ </Tab>+ <Tab value="TypeScript">+```typescript+// @noErrors+import { Composio } from '@composio/core';+const composio = new Composio({ apiKey: 'your_api_key' });+// ---cut---+// List every SHARED connection the caller has visibility into.+const shared = await composio.connectedAccounts.list({ accountType: "SHARED" });++for (const item of shared.items) {+ console.log(item.id, item.toolkit.slug);+}++// Scope to a single user's SHARED connections.+const sharedForAlice = await composio.connectedAccounts.list({+ accountType: "SHARED",+ userIds: ["user_alice"],+});+```+ </Tab>+</Tabs>+## Inspecting the ACL`get()` and `list()` responses surface `accountType` and `aclConfigForShared` under the same `experimental` block as the request shape. The `aclConfigForShared` field is populated only when the caller is the connection's creator or is using an API key — other callers see the `experimental` block without that field.@@ -346,14 +396,13 @@ except exceptions.ComposioSharedAccessDeniedError as e:// @noErrorsimport {Composio,- experimental_updateAcl,ComposioAclOnlyForSharedError,ComposioSharedAccessDeniedError,} from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---try {- await experimental_updateAcl(composio, "ca_private_gmail", {+ await composio.experimental.updateAcl("ca_private_gmail", {allowAllUsers: true,});} catch (error) {