1
+---
2
+title: Shared Connections
3
+description: Make a connected account usable by multiple users with a per-user access control list
4
+keywords: [shared connection, account type, SHARED, PRIVATE, ACL, allow all users, allowed user ids, not allowed user ids]
5
+llmGuardrails: "direct-execution"
6
+---
7
+
8
+<Callout type="info">
9
+If you're building an agent, prefer [sessions](/docs/configuring-sessions). Sessions let you pin a shared connection into a session config; see [Using a shared connection in a session](#using-a-shared-connection) below.
10
+</Callout>
11
+
12
+By default, a connected account is **PRIVATE** — only the `userId` that created it can use it. A **SHARED** connection can be reached by other `userId`s, subject to a per-connection access control list (ACL).
13
+
14
+Typical use cases:
15
+
16
+- **Org-managed credentials** — one Gmail / Salesforce / GitHub connection that every user in your app can call against, without each user having to authenticate separately.
17
+- **Background agents acting on behalf of multiple users** — the agent runs as a single service account but executes work for many `userId`s.
18
+- **Team mailboxes** — `support@` or `sales@` accounts where any teammate can send/read mail through your app.
19
+
20
+## SHARED vs PRIVATE
21
+
22
+| | PRIVATE (default) | SHARED |
23
+|---|---|---|
24
+| **Who can use it** | Only the owning `userId` | The creator + every `userId` permitted by the ACL |
25
+| **Default access for other users** | Always denied | Deny-by-default — the creator must grant access explicitly |
26
+| **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 |
27
+| **ACL fields** | Ignored | `allowAllUsers`, `allowedUserIds`, `notAllowedUserIds` |
28
+
29
+<Callout type="info">
30
+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.
31
+</Callout>
32
+
33
+## Creating a SHARED connection
34
+
35
+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).
36
+
37
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
38
+ <Tab value="Python">
39
+```python
40
+# Create a SHARED Gmail connection that any userId can use,
41
+# except `user_bob`.
42
+connection_request = composio.connected_accounts.link(
43
+ user_id="user_admin",
44
+ auth_config_id="ac_gmail_shared",
45
+ account_type="SHARED",
46
+ acl_config_for_shared={
47
+ "allow_all_users": True,
48
+ "not_allowed_user_ids": ["user_bob"],
49
+ },
50
+)
51
+print(connection_request.redirect_url)
52
+
53
+# Have user_admin complete the OAuth flow at the redirect URL,
54
+# then wait for the connection to become ACTIVE.
55
+connected = connection_request.wait_for_connection()
56
+print(f"Shared connection ready: {connected.id}")
57
+```
58
+ </Tab>
59
+ <Tab value="TypeScript">
60
+```typescript
61
+import { Composio } from '@composio/core';
62
+const composio = new Composio({ apiKey: 'your_api_key' });
63
+// ---cut---
64
+// Create a SHARED Gmail connection that any userId can use,
65
+// except `user_bob`.
66
+const connectionRequest = await composio.connectedAccounts.link(
67
+ "user_admin",
68
+ "ac_gmail_shared",
69
+ {
70
+ accountType: "SHARED",
71
+ aclConfigForShared: {
72
+ allowAllUsers: true,
73
+ notAllowedUserIds: ["user_bob"],
74
+ },
75
+ },
76
+);
77
+console.log(connectionRequest.redirectUrl);
78
+
79
+// Have user_admin complete the OAuth flow at the redirect URL,
80
+// then wait for the connection to become ACTIVE.
81
+const connected = await connectionRequest.waitForConnection();
82
+console.log(`Shared connection ready: ${connected.id}`);
83
+```
84
+ </Tab>
85
+</Tabs>
86
+
87
+The returned `connectedAccountId` (`ca_...`) is the ID you'll pin into other users' sessions.
88
+
89
+<Callout type="warn">
90
+ACL fields are only valid on SHARED connections. Sending `aclConfigForShared` on a PRIVATE connection raises `ComposioAclOnlyForSharedError`.
91
+</Callout>
92
+
93
+## ACL resolution rule
94
+
95
+When a non-creator `userId` attempts to use a SHARED connection, the ACL is evaluated in this order:
96
+
97
+1. `userId` ∈ `notAllowedUserIds` → **DENY**
98
+2. `allowAllUsers === true` → **ALLOW**
99
+3. `userId` ∈ `allowedUserIds` → **ALLOW**
100
+4. otherwise → **DENY** *(deny-by-default)*
101
+
102
+Deny wins on conflict, which lets you express *"share with everyone except a few people"* by setting `allowAllUsers: true` and naming the exceptions in `notAllowedUserIds`.
103
+
104
+The creator can always use their own connection — the ACL only governs other `userId`s.
105
+
106
+### Common ACL patterns
107
+
108
+| Goal | Configuration |
109
+|---|---|
110
+| **Only the creator** (default) | `{}` (or omit `aclConfigForShared`) |
111
+| **Allow every `userId`** | `{ allowAllUsers: true }` |
112
+| **Targeted allow list** | `{ allowedUserIds: ["user_alice", "user_bob"] }` |
113
+| **Everyone except a few users** | `{ allowAllUsers: true, notAllowedUserIds: ["user_bob"] }` |
114
+| **Combined: open + targeted deny** | `{ allowAllUsers: true, notAllowedUserIds: ["user_bob"], allowedUserIds: ["user_alice"] }` — Bob still denied (deny wins) |
115
+
116
+Each list accepts up to 1000 entries; each `userId` is 1..256 characters.
117
+
118
+## Updating the ACL
119
+
120
+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.
121
+
122
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
123
+ <Tab value="Python">
124
+```python
125
+# Open access to everyone.
126
+composio.connected_accounts.update_acl(
127
+ "ca_gmail_shared",
128
+ allow_all_users=True,
129
+)
130
+
131
+# Add a targeted allow list (without touching the wildcard or deny list).
132
+composio.connected_accounts.update_acl(
133
+ "ca_gmail_shared",
134
+ allowed_user_ids=["user_alice", "user_bob"],
135
+)
136
+
137
+# Revoke the allow list — only the creator can use it again
138
+# (unless allow_all_users is True).
139
+composio.connected_accounts.update_acl(
140
+ "ca_gmail_shared",
141
+ allowed_user_ids=[],
142
+)
143
+```
144
+ </Tab>
145
+ <Tab value="TypeScript">
146
+```typescript
147
+import { Composio } from '@composio/core';
148
+const composio = new Composio({ apiKey: 'your_api_key' });
149
+// ---cut---
150
+// Open access to everyone.
151
+await composio.connectedAccounts.updateAcl("ca_gmail_shared", {
152
+ allowAllUsers: true,
153
+});
154
+
155
+// Add a targeted allow list (without touching the wildcard or deny list).
156
+await composio.connectedAccounts.updateAcl("ca_gmail_shared", {
157
+ allowedUserIds: ["user_alice", "user_bob"],
158
+});
159
+
160
+// Revoke the allow list — only the creator can use it again
161
+// (unless allowAllUsers is true).
162
+await composio.connectedAccounts.updateAcl("ca_gmail_shared", {
163
+ allowedUserIds: [],
164
+});
165
+```
166
+ </Tab>
167
+</Tabs>
168
+
169
+<Callout type="warn">
170
+Passing `notAllowedUserIds: []` **clears the deny list**, which silently re-grants access to users you previously blocked. Always audit the allow side when clearing a deny list.
171
+</Callout>
172
+
173
+ACL writes are restricted to the connection's creator or an API key caller. Other callers receive a permission error.
174
+
175
+## Using a shared connection
176
+
177
+### In a tool-router session
178
+
179
+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.
180
+
181
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
182
+ <Tab value="Python">
183
+```python
184
+# user_alice starts a session that pins the shared Gmail connection.
185
+# Gmail tools loaded from this session will resolve to that connection
186
+# even though user_alice did not create it.
187
+session = composio.create(
188
+ user_id="user_alice",
189
+ connected_accounts={
190
+ "gmail": ["ca_gmail_shared"],
191
+ },
192
+)
193
+
194
+tools = session.tools()
195
+```
196
+ </Tab>
197
+ <Tab value="TypeScript">
198
+```typescript
199
+import { Composio } from '@composio/core';
200
+const composio = new Composio({ apiKey: 'your_api_key' });
201
+// ---cut---
202
+// user_alice starts a session that pins the shared Gmail connection.
203
+// Gmail tools loaded from this session will resolve to that connection
204
+// even though user_alice did not create it.
205
+const session = await composio.create("user_alice", {
206
+ connectedAccounts: {
207
+ gmail: ["ca_gmail_shared"],
208
+ },
209
+});
210
+
211
+const tools = await session.tools();
212
+```
213
+ </Tab>
214
+</Tabs>
215
+
216
+<Callout type="info">
217
+A session may pin **at most one SHARED connection per toolkit**. Pinning two SHARED Gmail connections in the same session is rejected at session create time. Mixing one SHARED with multiple PRIVATE pins is allowed.
218
+</Callout>
219
+
220
+### Direct execution
221
+
222
+Pass the SHARED connection's ID explicitly via `connectedAccountId`:
223
+
224
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
225
+ <Tab value="Python">
226
+```python
227
+result = composio.tools.execute(
228
+ slug="GMAIL_SEND_EMAIL",
229
+ user_id="user_alice",
230
+ connected_account_id="ca_gmail_shared",
231
+ arguments={"to": "person@example.com", "subject": "hi", "body": "..."},
232
+)
233
+```
234
+ </Tab>
235
+ <Tab value="TypeScript">
236
+```typescript
237
+import { Composio } from '@composio/core';
238
+const composio = new Composio({ apiKey: 'your_api_key' });
239
+// ---cut---
240
+const result = await composio.tools.execute("GMAIL_SEND_EMAIL", {
241
+ userId: "user_alice",
242
+ connectedAccountId: "ca_gmail_shared",
243
+ arguments: { to: "person@example.com", subject: "hi", body: "..." },
244
+});
245
+```
246
+ </Tab>
247
+</Tabs>
248
+
249
+If `user_alice` isn't permitted by the connection's ACL, the call raises `ComposioSharedAccessDeniedError`.
250
+
251
+## Inspecting the ACL
252
+
253
+`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.
254
+
255
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
256
+ <Tab value="Python">
257
+```python
258
+account = composio.connected_accounts.get("ca_gmail_shared")
259
+
260
+print(f"Type: {account.account_type}") # "PRIVATE" or "SHARED"
261
+
262
+if account.acl_config_for_shared:
263
+ acl = account.acl_config_for_shared
264
+ print(f"Allow all users: {acl.allow_all_users}")
265
+ print(f"Allowed: {acl.allowed_user_ids}")
266
+ print(f"Denied: {acl.not_allowed_user_ids}")
267
+else:
268
+ # You're not authorised to see the ACL on this connection.
269
+ print("ACL hidden")
270
+```
271
+ </Tab>
272
+ <Tab value="TypeScript">
273
+```typescript
274
+import { Composio } from '@composio/core';
275
+const composio = new Composio({ apiKey: 'your_api_key' });
276
+// ---cut---
277
+const account = await composio.connectedAccounts.get("ca_gmail_shared");
278
+
279
+console.log("Type:", account.accountType); // "PRIVATE" or "SHARED"
280
+
281
+if (account.aclConfigForShared) {
282
+ const acl = account.aclConfigForShared;
283
+ console.log("Allow all users:", acl.allowAllUsers);
284
+ console.log("Allowed:", acl.allowedUserIds);
285
+ console.log("Denied:", acl.notAllowedUserIds);
286
+} else {
287
+ // You're not authorised to see the ACL on this connection.
288
+ console.log("ACL hidden");
289
+}
290
+```
291
+ </Tab>
292
+</Tabs>
293
+
294
+## Error handling
295
+
296
+| Error | When |
297
+|---|---|
298
+| `ComposioAclOnlyForSharedError` (400) | ACL fields sent on a PRIVATE connection (at create or update time). |
299
+| `ComposioSharedAccessDeniedError` (403) | Direct execute with a SHARED `connectedAccountId` that the requesting `userId` isn't permitted to use. |
300
+| `ComposioSharedConnectionNotAccessibleError` (400) | A tool-router session pinned a SHARED connection that the session's `userId` cannot use — the error is raised at session create time, so the session never enters a state that fails mid-execution. |
301
+
302
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
303
+ <Tab value="Python">
304
+```python
305
+from composio import exceptions
306
+
307
+try:
308
+ composio.connected_accounts.update_acl(
309
+ "ca_private_gmail", # this connection is PRIVATE
310
+ allow_all_users=True,
311
+ )
312
+except exceptions.ComposioAclOnlyForSharedError as e:
313
+ print(f"ACL only applies to SHARED connections: {e}")
314
+
315
+try:
316
+ composio.tools.execute(
317
+ slug="GMAIL_SEND_EMAIL",
318
+ user_id="user_bob", # not on the allow list
319
+ connected_account_id="ca_gmail_shared",
320
+ arguments={...},
321
+ )
322
+except exceptions.ComposioSharedAccessDeniedError as e:
323
+ print(f"Access denied: {e}")
324
+```
325
+ </Tab>
326
+ <Tab value="TypeScript">
327
+```typescript
328
+import { Composio } from '@composio/core';
329
+import {
330
+ ComposioAclOnlyForSharedError,
331
+ ComposioSharedAccessDeniedError,
332
+} from '@composio/core';
333
+const composio = new Composio({ apiKey: 'your_api_key' });
334
+// ---cut---
335
+try {
336
+ await composio.connectedAccounts.updateAcl("ca_private_gmail", {
337
+ allowAllUsers: true,
338
+ });
339
+} catch (error) {
340
+ if (error instanceof ComposioAclOnlyForSharedError) {
341
+ console.log(`ACL only applies to SHARED connections: ${error.message}`);
342
+ }
343
+}
344
+
345
+try {
346
+ await composio.tools.execute("GMAIL_SEND_EMAIL", {
347
+ userId: "user_bob", // not on the allow list
348
+ connectedAccountId: "ca_gmail_shared",
349
+ arguments: { /* ... */ },
350
+ });
351
+} catch (error) {
352
+ if (error instanceof ComposioSharedAccessDeniedError) {
353
+ console.log(`Access denied: ${error.message}`);
354
+ }
355
+}
356
+```
357
+ </Tab>
358
+</Tabs>
359
+
360
+## What to read next
361
+
362
+<Cards>
363
+ <Card icon={<Database />} title="Connected accounts" href="/docs/auth-configuration/connected-accounts" description="Manage and monitor user connections to toolkits" />
364
+ <Card icon={<Plug />} title="Managing multiple connected accounts" href="/docs/managing-multiple-connected-accounts" description="Pin specific accounts into a session at runtime" />
365
+ <Card icon={<Wrench />} title="Configuring sessions" href="/docs/configuring-sessions" description="Session config — custom auth configs, pinned connections, multi-account" />
366
+</Cards>