@devries-cameron20 / composio Mirror · read-only / commits / c31ffce2e
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: add Shared Connections page under Authentication

New page at /docs/auth-configuration/shared-connections covers the account_type and per-user ACL surface added to the Connected Accounts SDK in 0.9.1: - When to use SHARED vs PRIVATE (table) - Creating a SHARED connection via link() with an initial ACL - The 4-step deny-wins resolution rule + common ACL patterns - updateAcl() with PATCH semantics + empty-array footgun warning - Using a shared connection from a tool-router session (pinning) or via direct execute with connectedAccountId - Inspecting account_type + aclConfigForShared on get() responses - Error handling table covering ComposioAclOnlyForSharedError, ComposioSharedAccessDeniedError, ComposioSharedConnectionNotAccessibleError Other changes: - Bump docs/package.json @composio/core dependency from ^0.9.0 to ^0.9.1 so twoslash type-checks against the version that exposes the new fields. - Wire the new page into the Authentication sidebar between connected-accounts and migrating-initiate-to-link. Verified: bun run build clean (1411 pages including the new one). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

venkat82 committed May 12, 2026 at 12:07 UTC c31ffce2e41459b93b5511fe3adf1086295e48c7
4 files changed +371 -5
docs/bun.lock
+3 -4
@@ -1,6 +1,5 @@
1 {
2 "lockfileVersion": 1,
3 - "configVersion": 0,
3 "workspaces": {
4 "": {
5 "name": "fumadocs",
@@ -32,7 +31,7 @@
31 "@anthropic-ai/sdk": "^0.71.2",
32 "@composio/anthropic": "^0.5.5",
33 "@composio/claude-agent-sdk": "^0.6.3",
35 - "@composio/core": "^0.9.0",
34 + "@composio/core": "^0.9.1",
35 "@composio/google": "^0.5.5",
36 "@composio/langchain": "^0.5.5",
37 "@composio/llamaindex": "^0.5.5",
@@ -164,9 +163,9 @@
163
164 "@composio/claude-agent-sdk": ["@composio/claude-agent-sdk@0.6.3", "", { "dependencies": { "zod": "^3.25.76" }, "peerDependencies": { "@anthropic-ai/claude-agent-sdk": ">=0.1.0", "@composio/core": "0.6.3" } }, "sha512-724KwTShuore9zQrxRvbOzVrqZ8w9Z5ZkzElKYJX6mbUq33GaVs5bFbgSomNDaRe9kkLAI7fPP8WteZJB32akA=="],
165
167 - "@composio/client": ["@composio/client@0.1.0-alpha.70", "", {}, "sha512-bANvjHL9aYwvzcrDL9S2W/uTf6EV3slIpYRL3lAv3k74tTgB1TkYzAWgxxz1OpLK86iDB5xq3RFlritVu23Erg=="],
166 + "@composio/client": ["@composio/client@0.1.0-alpha.71", "", {}, "sha512-6h1IPMbXIx5PjaU0T+a1MNnKHL/pPP7+X2nNQaler5XoENANWGm4mYePjR+7Cgtw1j6X2QkCmRLuX5q9c0INvQ=="],
167
169 - "@composio/core": ["@composio/core@0.9.0", "", { "dependencies": { "@composio/client": "0.1.0-alpha.70", "@composio/json-schema-to-zod": "0.1.20", "@types/json-schema": "^7.0.15", "chalk": "^4.1.2", "openai": "^6.16.0", "pusher-js": "^8.4.0", "semver": "^7.7.2", "zod-to-json-schema": "^3.25.1" }, "peerDependencies": { "zod": "^3.25 || ^4" } }, "sha512-7gZx1nzHUxGiutPZZQov4va4N69MIbvJlkfZAQd0yG/n0znqntBKbUfF6/GucmBzxwgX58gsS9z512ThVVGOEw=="],
168 + "@composio/core": ["@composio/core@0.9.1", "", { "dependencies": { "@composio/client": "0.1.0-alpha.71", "@composio/json-schema-to-zod": "0.1.20", "@types/json-schema": "^7.0.15", "chalk": "^4.1.2", "openai": "^6.16.0", "pusher-js": "^8.4.0", "semver": "^7.7.2", "zod-to-json-schema": "^3.25.1" }, "peerDependencies": { "zod": "^3.25 || ^4" } }, "sha512-9y3PJ6GiIdX3SIsLRV+vByhJ3L5+5CwH6RjKaT1McnVd6unIiKJ4DZxi1NcYs5O0J0R5gyCBvxo+CAJ5sDdDeQ=="],
169
170 "@composio/google": ["@composio/google@0.5.5", "", { "peerDependencies": { "@composio/core": "0.5.5", "@google/genai": "^1.1.0" } }, "sha512-0W+WZANsVSVAkhaRxbUUpuHJ52O3BbknAEV/C38/1yZq3mmvzx/DlRjGf/tiDRaS7Pxr8WhYwGUKgeyzYR4qAw=="],
171
docs/content/docs/auth-configuration/meta.json
+1
@@ -7,6 +7,7 @@
7 "programmatic-auth-configs",
8 "custom-auth-params",
9 "connected-accounts",
10 + "shared-connections",
11 "migrating-initiate-to-link"
12 ]
13 }
docs/content/docs/auth-configuration/shared-connections.mdx new
+366
@@ -0,0 +1,366 @@
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>
docs/package.json
+1 -1
@@ -44,7 +44,7 @@
44 "@anthropic-ai/sdk": "^0.71.2",
45 "@composio/anthropic": "^0.5.5",
46 "@composio/claude-agent-sdk": "^0.6.3",
47 - "@composio/core": "^0.9.0",
47 + "@composio/core": "^0.9.1",
48 "@composio/google": "^0.5.5",
49 "@composio/langchain": "^0.5.5",
50 "@composio/llamaindex": "^0.5.5",