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 code samples with experimental wire shape (hermes#9960)
venkat8222557104f975
diff --git a/docs/content/docs/auth-configuration/shared-connections.mdx b/docs/content/docs/auth-configuration/shared-connections.mdxindex 4f147dcb2..02c21d128 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. 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.+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.</Callout><Callout type="info">@@ -28,7 +28,7 @@ Typical use cases:| **Who can use it** | Only the owning `userId` | The creator + every `userId` permitted by the ACL || **Default access for other users** | Always denied | Deny-by-default — the creator must grant access explicitly || **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 |-| **ACL fields** | Ignored | `allowAllUsers`, `allowedUserIds`, `notAllowedUserIds` |+| **ACL fields** | Ignored | `allowAllUsers`, `allowedUserIds`, `notAllowedUserIds` (inside the `experimental` block) |<Callout type="info">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## Creating a SHARED connection-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).+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).<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">@@ -46,10 +46,12 @@ Pass `accountType: "SHARED"` to `link()`. Optionally pass an initial ACL — omiconnection_request = composio.connected_accounts.link(user_id="user_admin",auth_config_id="ac_gmail_shared",- account_type="SHARED",- acl_config_for_shared={- "allow_all_users": True,- "not_allowed_user_ids": ["user_bob"],+ experimental={+ "account_type": "SHARED",+ "acl_config_for_shared": {+ "allow_all_users": True,+ "not_allowed_user_ids": ["user_bob"],+ },},)print(connection_request.redirect_url)@@ -62,6 +64,7 @@ print(f"Shared connection ready: {connected.id}")</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---@@ -71,10 +74,12 @@ const connectionRequest = await composio.connectedAccounts.link("user_admin","ac_gmail_shared",{- accountType: "SHARED",- aclConfigForShared: {- allowAllUsers: true,- notAllowedUserIds: ["user_bob"],+ experimental: {+ accountType: "SHARED",+ aclConfigForShared: {+ allowAllUsers: true,+ notAllowedUserIds: ["user_bob"],+ },},},);@@ -91,7 +96,7 @@ console.log(`Shared connection ready: ${connected.id}`);The returned `connectedAccountId` (`ca_...`) is the ID you'll pin into other users' sessions.<Callout type="warn">-ACL fields are only valid on SHARED connections. Sending `aclConfigForShared` on a PRIVATE connection raises `ComposioAclOnlyForSharedError`.+ACL fields are only valid on SHARED connections. Sending an `experimental.acl_config_for_shared` block on a PRIVATE connection raises `ComposioAclOnlyForSharedError`.</Callout>## ACL resolution rule@@ -109,9 +114,11 @@ The creator can always use their own connection — the ACL only governs other `### Common ACL patterns-| Goal | Configuration |+The table below shows the inner shape of `acl_config_for_shared` — wrap it inside the `experimental` block at the call site.++| Goal | `acl_config_for_shared` ||---|---|-| **Only the creator** (default) | `{}` (or omit `aclConfigForShared`) |+| **Only the creator** (default) | `{}` (or omit the block) || **Allow every `userId`** | `{ allowAllUsers: true }` || **Targeted allow list** | `{ allowedUserIds: ["user_alice", "user_bob"] }` || **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.## Updating the ACL-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.+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.<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```python# Open access to everyone.-composio.connected_accounts.update_acl(+composio.experimental.update_acl("ca_gmail_shared",allow_all_users=True,)# Add a targeted allow list (without touching the wildcard or deny list).-composio.connected_accounts.update_acl(+composio.experimental.update_acl("ca_gmail_shared",allowed_user_ids=["user_alice", "user_bob"],)# Revoke the allow list — only the creator can use it again# (unless allow_all_users is True).-composio.connected_accounts.update_acl(+composio.experimental.update_acl("ca_gmail_shared",allowed_user_ids=[],)@@ -148,22 +155,23 @@ composio.connected_accounts.update_acl(</Tab><Tab value="TypeScript">```typescript-import { Composio } from '@composio/core';+// @noErrors+import { Composio, experimental_updateAcl } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---// Open access to everyone.-await composio.connectedAccounts.updateAcl("ca_gmail_shared", {+await experimental_updateAcl(composio, "ca_gmail_shared", {allowAllUsers: true,});// Add a targeted allow list (without touching the wildcard or deny list).-await composio.connectedAccounts.updateAcl("ca_gmail_shared", {+await experimental_updateAcl(composio, "ca_gmail_shared", {allowedUserIds: ["user_alice", "user_bob"],});// Revoke the allow list — only the creator can use it again// (unless allowAllUsers is true).-await composio.connectedAccounts.updateAcl("ca_gmail_shared", {+await experimental_updateAcl(composio, "ca_gmail_shared", {allowedUserIds: [],});```@@ -182,6 +190,8 @@ ACL writes are restricted to the connection's creator or an API key caller. OthePin 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.+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.+<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```python@@ -254,42 +264,46 @@ If `user_alice` isn't permitted by the connection's ACL, the call raises `Compos## Inspecting the ACL-`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.+`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.<Tabs groupId="language" items={['Python', 'TypeScript']} persist><Tab value="Python">```pythonaccount = composio.connected_accounts.get("ca_gmail_shared")-print(f"Type: {account.account_type}") # "PRIVATE" or "SHARED"--if account.acl_config_for_shared:- acl = account.acl_config_for_shared- print(f"Allow all users: {acl.allow_all_users}")- print(f"Allowed: {acl.allowed_user_ids}")- print(f"Denied: {acl.not_allowed_user_ids}")-else:- # You're not authorised to see the ACL on this connection.- print("ACL hidden")+if account.experimental:+ print(f"Type: {account.experimental.account_type}") # "PRIVATE" or "SHARED"++ if account.experimental.acl_config_for_shared:+ acl = account.experimental.acl_config_for_shared+ print(f"Allow all users: {acl.allow_all_users}")+ print(f"Allowed: {acl.allowed_user_ids}")+ print(f"Denied: {acl.not_allowed_user_ids}")+ else:+ # You're not authorised to see the ACL on this connection.+ print("ACL hidden")```</Tab><Tab value="TypeScript">```typescript+// @noErrorsimport { Composio } from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---const account = await composio.connectedAccounts.get("ca_gmail_shared");-console.log("Type:", account.accountType); // "PRIVATE" or "SHARED"--if (account.aclConfigForShared) {- const acl = account.aclConfigForShared;- console.log("Allow all users:", acl.allowAllUsers);- console.log("Allowed:", acl.allowedUserIds);- console.log("Denied:", acl.notAllowedUserIds);-} else {- // You're not authorised to see the ACL on this connection.- console.log("ACL hidden");+if (account.experimental) {+ console.log("Type:", account.experimental.accountType); // "PRIVATE" or "SHARED"++ if (account.experimental.aclConfigForShared) {+ const acl = account.experimental.aclConfigForShared;+ console.log("Allow all users:", acl.allowAllUsers);+ console.log("Allowed:", acl.allowedUserIds);+ console.log("Denied:", acl.notAllowedUserIds);+ } else {+ // You're not authorised to see the ACL on this connection.+ console.log("ACL hidden");+ }}```</Tab>@@ -309,7 +323,7 @@ if (account.aclConfigForShared) {from composio import exceptionstry:- composio.connected_accounts.update_acl(+ composio.experimental.update_acl("ca_private_gmail", # this connection is PRIVATEallow_all_users=True,)@@ -329,15 +343,17 @@ except exceptions.ComposioSharedAccessDeniedError as e:</Tab><Tab value="TypeScript">```typescript-import { Composio } from '@composio/core';+// @noErrorsimport {+ Composio,+ experimental_updateAcl,ComposioAclOnlyForSharedError,ComposioSharedAccessDeniedError,} from '@composio/core';const composio = new Composio({ apiKey: 'your_api_key' });// ---cut---try {- await composio.connectedAccounts.updateAcl("ca_private_gmail", {+ await experimental_updateAcl(composio, "ca_private_gmail", {allowAllUsers: true,});} catch (error) {