@devries-cameron20 / composio Mirror · read-only / commits / 22557104f
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 code samples with experimental wire shape (hermes#9960)

The previous samples called the flat-field surface that `@composio/core@0.9.1` and `composio==0.14.0` shipped. The wire is being restructured by hermes#9960 to nest those fields under an `experimental` block, and the follow-up SDK PRs will move the call sites to a matching `experimental` namespace (mirroring the custom-tools precedent of `experimental_createTool` / `composio.experimental.tool`). This commit updates every code sample to the post-restructure shape so the doc is internally consistent with the experimental rollout it advertises in the top callout. Specific changes: - `link()`: `experimental: { accountType, aclConfigForShared }` (TS) / `experimental={"account_type": ..., "acl_config_for_shared": ...}` (Py). - `updateAcl()` → `experimental_updateAcl(client, id, opts)` (TS top-level export, mirrors `experimental_createTool`) / `composio.experimental.update_acl(id, ...)` (Py, mirrors `composio.experimental.tool`). - Retrieve response inspection now reads from `account.experimental?.accountType` / `account.experimental?.aclConfigForShared` to match the response shape. - Error-handling examples use the experimental method names too. - Common ACL patterns table clarifies the inner shape is wrapped inside the `experimental` block at the call site. - Top callout updated to call out the namespace move so readers know what they're looking at. TypeScript blocks that target the post-restructure surface carry `// @noErrors` because the published `@composio/core@0.9.1` doesn't yet expose `experimental_updateAcl` or the nested `experimental` options on `link()`. The directives will come out in a follow-up docs PR once the SDK PRs publish. Pinning a SHARED connection in a session (`connectedAccounts: { gmail: [...] }`) and direct execute (`composio.tools.execute(slug, { connectedAccountId })`) stay unchanged — session config and execute aren't part of the experimental wire restructure. Verified: bun run build clean (1411 pages, no twoslash errors with @noErrors). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

venkat82 committed May 12, 2026 at 18:44 UTC 22557104f9758ba97286db9d68e2288465449191
1 file changed +62 -46
docs/content/docs/auth-configuration/shared-connections.mdx
+62 -46
@@ -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. Both the wire shape and SDK surface are being restructured into a `composio.experimental.*` namespace — pin a specific SDK version if you depend on the current shape.
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.
10 </Callout>
11
12 <Callout type="info">
@@ -28,7 +28,7 @@ Typical use cases:
28 | **Who can use it** | Only the owning `userId` | The creator + every `userId` permitted by the ACL |
29 | **Default access for other users** | Always denied | Deny-by-default — the creator must grant access explicitly |
30 | **How it's used** | Implicit lookup by `userId` | Must be **explicitly pinned** in a tool-router session, or referenced by `connectedAccountId` on a direct execute |
31 -| **ACL fields** | Ignored | `allowAllUsers`, `allowedUserIds`, `notAllowedUserIds` |
31 +| **ACL fields** | Ignored | `allowAllUsers`, `allowedUserIds`, `notAllowedUserIds` (inside the `experimental` block) |
32
33 <Callout type="info">
34 SHARED connections are never used implicitly. A session belonging to a non-creator `userId` will only resolve a SHARED connection if the developer explicitly pins it in the session config.
@@ -36,7 +36,7 @@ SHARED connections are never used implicitly. A session belonging to a non-creat
36
37 ## Creating a SHARED connection
38
39 -Pass `accountType: "SHARED"` to `link()`. Optionally pass an initial ACL — omit it to keep the default deny-by-default state (only the creator can use it until you grant access).
39 +Pass an `experimental` block to `link()` containing `account_type: "SHARED"` (and optionally an initial ACL). Omit the ACL block to keep the default deny-by-default state (only the creator can use it until you grant access).
40
41 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
42 <Tab value="Python">
@@ -46,10 +46,12 @@ Pass `accountType: "SHARED"` to `link()`. Optionally pass an initial ACL — omi
46 connection_request = composio.connected_accounts.link(
47 user_id="user_admin",
48 auth_config_id="ac_gmail_shared",
49 - account_type="SHARED",
50 - acl_config_for_shared={
51 - "allow_all_users": True,
52 - "not_allowed_user_ids": ["user_bob"],
49 + experimental={
50 + "account_type": "SHARED",
51 + "acl_config_for_shared": {
52 + "allow_all_users": True,
53 + "not_allowed_user_ids": ["user_bob"],
54 + },
55 },
56 )
57 print(connection_request.redirect_url)
@@ -62,6 +64,7 @@ print(f"Shared connection ready: {connected.id}")
64 </Tab>
65 <Tab value="TypeScript">
66 ```typescript
67 +// @noErrors
68 import { Composio } from '@composio/core';
69 const composio = new Composio({ apiKey: 'your_api_key' });
70 // ---cut---
@@ -71,10 +74,12 @@ const connectionRequest = await composio.connectedAccounts.link(
74 "user_admin",
75 "ac_gmail_shared",
76 {
74 - accountType: "SHARED",
75 - aclConfigForShared: {
76 - allowAllUsers: true,
77 - notAllowedUserIds: ["user_bob"],
77 + experimental: {
78 + accountType: "SHARED",
79 + aclConfigForShared: {
80 + allowAllUsers: true,
81 + notAllowedUserIds: ["user_bob"],
82 + },
83 },
84 },
85 );
@@ -91,7 +96,7 @@ console.log(`Shared connection ready: ${connected.id}`);
96 The returned `connectedAccountId` (`ca_...`) is the ID you'll pin into other users' sessions.
97
98 <Callout type="warn">
94 -ACL fields are only valid on SHARED connections. Sending `aclConfigForShared` on a PRIVATE connection raises `ComposioAclOnlyForSharedError`.
99 +ACL fields are only valid on SHARED connections. Sending an `experimental.acl_config_for_shared` block on a PRIVATE connection raises `ComposioAclOnlyForSharedError`.
100 </Callout>
101
102 ## ACL resolution rule
@@ -109,9 +114,11 @@ The creator can always use their own connection — the ACL only governs other `
114
115 ### Common ACL patterns
116
112 -| Goal | Configuration |
117 +The table below shows the inner shape of `acl_config_for_shared` — wrap it inside the `experimental` block at the call site.
118 +
119 +| Goal | `acl_config_for_shared` |
120 |---|---|
114 -| **Only the creator** (default) | `{}` (or omit `aclConfigForShared`) |
121 +| **Only the creator** (default) | `{}` (or omit the block) |
122 | **Allow every `userId`** | `{ allowAllUsers: true }` |
123 | **Targeted allow list** | `{ allowedUserIds: ["user_alice", "user_bob"] }` |
124 | **Everyone except a few users** | `{ allowAllUsers: true, notAllowedUserIds: ["user_bob"] }` |
@@ -121,26 +128,26 @@ Each list accepts up to 1000 entries; each `userId` is 1..256 characters.
128
129 ## Updating the ACL
130
124 -Use `updateAcl()` to change access after creation. PATCH semantics — pass only the fields you want to change; omit a field to leave it unchanged; pass an empty array to clear an allow/deny list.
131 +Use the experimental ACL-update method to change access after creation. PATCH semantics — pass only the fields you want to change; omit a field to leave it unchanged; pass an empty array to clear an allow/deny list.
132
133 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
134 <Tab value="Python">
135 ```python
136 # Open access to everyone.
130 -composio.connected_accounts.update_acl(
137 +composio.experimental.update_acl(
138 "ca_gmail_shared",
139 allow_all_users=True,
140 )
141
142 # Add a targeted allow list (without touching the wildcard or deny list).
136 -composio.connected_accounts.update_acl(
143 +composio.experimental.update_acl(
144 "ca_gmail_shared",
145 allowed_user_ids=["user_alice", "user_bob"],
146 )
147
148 # Revoke the allow list — only the creator can use it again
149 # (unless allow_all_users is True).
143 -composio.connected_accounts.update_acl(
150 +composio.experimental.update_acl(
151 "ca_gmail_shared",
152 allowed_user_ids=[],
153 )
@@ -148,22 +155,23 @@ composio.connected_accounts.update_acl(
155 </Tab>
156 <Tab value="TypeScript">
157 ```typescript
151 -import { Composio } from '@composio/core';
158 +// @noErrors
159 +import { Composio, experimental_updateAcl } from '@composio/core';
160 const composio = new Composio({ apiKey: 'your_api_key' });
161 // ---cut---
162 // Open access to everyone.
155 -await composio.connectedAccounts.updateAcl("ca_gmail_shared", {
163 +await experimental_updateAcl(composio, "ca_gmail_shared", {
164 allowAllUsers: true,
165 });
166
167 // Add a targeted allow list (without touching the wildcard or deny list).
160 -await composio.connectedAccounts.updateAcl("ca_gmail_shared", {
168 +await experimental_updateAcl(composio, "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).
166 -await composio.connectedAccounts.updateAcl("ca_gmail_shared", {
174 +await experimental_updateAcl(composio, "ca_gmail_shared", {
175 allowedUserIds: [],
176 });
177 ```
@@ -182,6 +190,8 @@ ACL writes are restricted to the connection's creator or an API key caller. Othe
190
191 Pin the SHARED connection into the session via `connectedAccounts`. The session belongs to a *different* `userId` than the creator — the pin is what makes the SHARED connection visible to that session.
192
193 +The session config itself is **not** experimental — only the connection that you're pinning is. So you pin by ID exactly as you would a PRIVATE connection.
194 +
195 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
196 <Tab value="Python">
197 ```python
@@ -254,42 +264,46 @@ If `user_alice` isn't permitted by the connection's ACL, the call raises `Compos
264
265 ## Inspecting the ACL
266
257 -`get()` and `list()` return the ACL on each SHARED connection — but only when the caller is the connection's creator or is using an API key. Other callers see the response without the `aclConfigForShared` field.
267 +`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.
268
269 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
270 <Tab value="Python">
271 ```python
272 account = composio.connected_accounts.get("ca_gmail_shared")
273
264 -print(f"Type: {account.account_type}") # "PRIVATE" or "SHARED"
265 -
266 -if account.acl_config_for_shared:
267 - acl = account.acl_config_for_shared
268 - print(f"Allow all users: {acl.allow_all_users}")
269 - print(f"Allowed: {acl.allowed_user_ids}")
270 - print(f"Denied: {acl.not_allowed_user_ids}")
271 -else:
272 - # You're not authorised to see the ACL on this connection.
273 - print("ACL hidden")
274 +if account.experimental:
275 + print(f"Type: {account.experimental.account_type}") # "PRIVATE" or "SHARED"
276 +
277 + if account.experimental.acl_config_for_shared:
278 + acl = account.experimental.acl_config_for_shared
279 + print(f"Allow all users: {acl.allow_all_users}")
280 + print(f"Allowed: {acl.allowed_user_ids}")
281 + print(f"Denied: {acl.not_allowed_user_ids}")
282 + else:
283 + # You're not authorised to see the ACL on this connection.
284 + print("ACL hidden")
285 ```
286 </Tab>
287 <Tab value="TypeScript">
288 ```typescript
289 +// @noErrors
290 import { Composio } from '@composio/core';
291 const composio = new Composio({ apiKey: 'your_api_key' });
292 // ---cut---
293 const account = await composio.connectedAccounts.get("ca_gmail_shared");
294
283 -console.log("Type:", account.accountType); // "PRIVATE" or "SHARED"
284 -
285 -if (account.aclConfigForShared) {
286 - const acl = account.aclConfigForShared;
287 - console.log("Allow all users:", acl.allowAllUsers);
288 - console.log("Allowed:", acl.allowedUserIds);
289 - console.log("Denied:", acl.notAllowedUserIds);
290 -} else {
291 - // You're not authorised to see the ACL on this connection.
292 - console.log("ACL hidden");
295 +if (account.experimental) {
296 + console.log("Type:", account.experimental.accountType); // "PRIVATE" or "SHARED"
297 +
298 + if (account.experimental.aclConfigForShared) {
299 + const acl = account.experimental.aclConfigForShared;
300 + console.log("Allow all users:", acl.allowAllUsers);
301 + console.log("Allowed:", acl.allowedUserIds);
302 + console.log("Denied:", acl.notAllowedUserIds);
303 + } else {
304 + // You're not authorised to see the ACL on this connection.
305 + console.log("ACL hidden");
306 + }
307 }
308 ```
309 </Tab>
@@ -309,7 +323,7 @@ if (account.aclConfigForShared) {
323 from composio import exceptions
324
325 try:
312 - composio.connected_accounts.update_acl(
326 + composio.experimental.update_acl(
327 "ca_private_gmail", # this connection is PRIVATE
328 allow_all_users=True,
329 )
@@ -329,15 +343,17 @@ except exceptions.ComposioSharedAccessDeniedError as e:
343 </Tab>
344 <Tab value="TypeScript">
345 ```typescript
332 -import { Composio } from '@composio/core';
346 +// @noErrors
347 import {
348 + Composio,
349 + experimental_updateAcl,
350 ComposioAclOnlyForSharedError,
351 ComposioSharedAccessDeniedError,
352 } from '@composio/core';
353 const composio = new Composio({ apiKey: 'your_api_key' });
354 // ---cut---
355 try {
340 - await composio.connectedAccounts.updateAcl("ca_private_gmail", {
356 + await experimental_updateAcl(composio, "ca_private_gmail", {
357 allowAllUsers: true,
358 });
359 } catch (error) {