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
| **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
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
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)
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---
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
);
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
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"] }` |
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
)
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
```
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
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>
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
)
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) {