@devries-cameron20 / composio Mirror · read-only / commits / 1292bc214
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, 21:00 UTC

docs(shared-connections): align with final SDK surface + add list filter section

Three updates after the post-review changes on the SDK PRs: 1. **TS `updateAcl` shape** — the review feedback on PR #3424 moved the call from a top-level `experimental_updateAcl(composio, id, opts)` export to a method on the `composio.experimental` namespace, mirroring Python (`composio.experimental.update_acl(id, ...)`). All TS code samples now call `composio.experimental.updateAcl(id, opts)`. The stale `experimental_updateAcl` import is dropped from the error-handling sample too. 2. **Top callout** — no longer mentions the discarded top-level export; reads as "the SDK methods live under the `composio.experimental` namespace" with both language names. 3. **Listing SHARED connections** — new section before "Inspecting the ACL". Shows the `account_type` (Py) / `accountType` (TS) filter that was missing from the doc. The wire keeps this flat as a query param (unlike the nested experimental block on create/update), so the SDK surface stays flat too — table of `PRIVATE` / `SHARED` / `ALL` and tabbed Python + TS examples scoping by user. Build: `bun run build` clean. TS blocks still carry `// @noErrors` because `@composio/core` on npm doesn't yet expose `composio.experimental.updateAcl` or the typed `accountType` filter — both ship in PR #3424. Those directives come out in a follow-up doc commit once the SDK publishes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

venkat82 committed May 13, 2026 at 20:42 UTC 1292bc21496d547d9f687965cab9370665ca43a5
1 file changed +56 -7
docs/content/docs/auth-configuration/shared-connections.mdx
+56 -7
@@ -6,7 +6,7 @@ llmGuardrails: "direct-execution"
6 ---
7
8 <Callout type="warn">
9 -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.
9 +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.
10 </Callout>
11
12 <Callout type="info">
@@ -156,22 +156,22 @@ composio.experimental.update_acl(
156 <Tab value="TypeScript">
157 ```typescript
158 // @noErrors
159 -import { Composio, experimental_updateAcl } from '@composio/core';
159 +import { Composio } from '@composio/core';
160 const composio = new Composio({ apiKey: 'your_api_key' });
161 // ---cut---
162 // Open access to everyone.
163 -await experimental_updateAcl(composio, "ca_gmail_shared", {
163 +await composio.experimental.updateAcl("ca_gmail_shared", {
164 allowAllUsers: true,
165 });
166
167 // Add a targeted allow list (without touching the wildcard or deny list).
168 -await experimental_updateAcl(composio, "ca_gmail_shared", {
168 +await composio.experimental.updateAcl("ca_gmail_shared", {
169 allowedUserIds: ["user_alice", "user_bob"],
170 });
171
172 // Revoke the allow list — only the creator can use it again
173 // (unless allowAllUsers is true).
174 -await experimental_updateAcl(composio, "ca_gmail_shared", {
174 +await composio.experimental.updateAcl("ca_gmail_shared", {
175 allowedUserIds: [],
176 });
177 ```
@@ -262,6 +262,56 @@ const result = await composio.tools.execute("GMAIL_SEND_EMAIL", {
262
263 If `user_alice` isn't permitted by the connection's ACL, the call raises `ComposioSharedAccessDeniedError`.
264
265 +## Listing SHARED connections
266 +
267 +By default `list()` returns **PRIVATE only** — shared accounts must be requested explicitly. Pass an `account_type` (Python) / `accountType` (TypeScript) filter to scope the query.
268 +
269 +| Value | Returns |
270 +|---|---|
271 +| `'PRIVATE'` *(default when omitted)* | Only PRIVATE connections |
272 +| `'SHARED'` | Only SHARED connections |
273 +| `'ALL'` | PRIVATE + SHARED |
274 +
275 +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`.
276 +
277 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
278 + <Tab value="Python">
279 +```python
280 +# List every SHARED connection the caller has visibility into.
281 +shared = composio.connected_accounts.list(account_type="SHARED")
282 +
283 +for item in shared.items:
284 + print(item.id, item.toolkit.slug)
285 +
286 +# Scope to a single user's SHARED connections.
287 +shared_for_alice = composio.connected_accounts.list(
288 + account_type="SHARED",
289 + user_ids=["user_alice"],
290 +)
291 +```
292 + </Tab>
293 + <Tab value="TypeScript">
294 +```typescript
295 +// @noErrors
296 +import { Composio } from '@composio/core';
297 +const composio = new Composio({ apiKey: 'your_api_key' });
298 +// ---cut---
299 +// List every SHARED connection the caller has visibility into.
300 +const shared = await composio.connectedAccounts.list({ accountType: "SHARED" });
301 +
302 +for (const item of shared.items) {
303 + console.log(item.id, item.toolkit.slug);
304 +}
305 +
306 +// Scope to a single user's SHARED connections.
307 +const sharedForAlice = await composio.connectedAccounts.list({
308 + accountType: "SHARED",
309 + userIds: ["user_alice"],
310 +});
311 +```
312 + </Tab>
313 +</Tabs>
314 +
315 ## Inspecting the ACL
316
317 `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:
396 // @noErrors
397 import {
398 Composio,
349 - experimental_updateAcl,
399 ComposioAclOnlyForSharedError,
400 ComposioSharedAccessDeniedError,
401 } from '@composio/core';
402 const composio = new Composio({ apiKey: 'your_api_key' });
403 // ---cut---
404 try {
356 - await experimental_updateAcl(composio, "ca_private_gmail", {
405 + await composio.experimental.updateAcl("ca_private_gmail", {
406 allowAllUsers: true,
407 });
408 } catch (error) {