Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: add Shared Connections page under Authentication

venkat82c31ffce2e414
diff --git a/docs/bun.lock b/docs/bun.lock
index f34f00d75..96f1e5674 100644
--- a/docs/bun.lock
+++ b/docs/bun.lock
@@ -1,6 +1,5 @@
{
"lockfileVersion": 1,
- "configVersion": 0,
"workspaces": {
"": {
"name": "fumadocs",
@@ -32,7 +31,7 @@
"@anthropic-ai/sdk": "^0.71.2",
"@composio/anthropic": "^0.5.5",
"@composio/claude-agent-sdk": "^0.6.3",
- "@composio/core": "^0.9.0",
+ "@composio/core": "^0.9.1",
"@composio/google": "^0.5.5",
"@composio/langchain": "^0.5.5",
"@composio/llamaindex": "^0.5.5",
@@ -164,9 +163,9 @@
"@composio/claude-agent-sdk": ["@composio/[email protected]", "", { "dependencies": { "zod": "^3.25.76" }, "peerDependencies": { "@anthropic-ai/claude-agent-sdk": ">=0.1.0", "@composio/core": "0.6.3" } }, "sha512-724KwTShuore9zQrxRvbOzVrqZ8w9Z5ZkzElKYJX6mbUq33GaVs5bFbgSomNDaRe9kkLAI7fPP8WteZJB32akA=="],
- "@composio/client": ["@composio/[email protected]", "", {}, "sha512-bANvjHL9aYwvzcrDL9S2W/uTf6EV3slIpYRL3lAv3k74tTgB1TkYzAWgxxz1OpLK86iDB5xq3RFlritVu23Erg=="],
+ "@composio/client": ["@composio/[email protected]", "", {}, "sha512-6h1IPMbXIx5PjaU0T+a1MNnKHL/pPP7+X2nNQaler5XoENANWGm4mYePjR+7Cgtw1j6X2QkCmRLuX5q9c0INvQ=="],
- "@composio/core": ["@composio/[email protected]", "", { "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=="],
+ "@composio/core": ["@composio/[email protected]", "", { "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=="],
"@composio/google": ["@composio/[email protected]", "", { "peerDependencies": { "@composio/core": "0.5.5", "@google/genai": "^1.1.0" } }, "sha512-0W+WZANsVSVAkhaRxbUUpuHJ52O3BbknAEV/C38/1yZq3mmvzx/DlRjGf/tiDRaS7Pxr8WhYwGUKgeyzYR4qAw=="],
diff --git a/docs/content/docs/auth-configuration/meta.json b/docs/content/docs/auth-configuration/meta.json
index dee687b3f..57c81fe0e 100644
--- a/docs/content/docs/auth-configuration/meta.json
+++ b/docs/content/docs/auth-configuration/meta.json
@@ -7,6 +7,7 @@
"programmatic-auth-configs",
"custom-auth-params",
"connected-accounts",
+ "shared-connections",
"migrating-initiate-to-link"
]
}
diff --git a/docs/content/docs/auth-configuration/shared-connections.mdx b/docs/content/docs/auth-configuration/shared-connections.mdx
new file mode 100644
index 000000000..44f9302be
--- /dev/null
+++ b/docs/content/docs/auth-configuration/shared-connections.mdx
@@ -0,0 +1,366 @@
+---
+title: Shared Connections
+description: Make a connected account usable by multiple users with a per-user access control list
+keywords: [shared connection, account type, SHARED, PRIVATE, ACL, allow all users, allowed user ids, not allowed user ids]
+llmGuardrails: "direct-execution"
+---
+
+<Callout type="info">
+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.
+</Callout>
+
+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).
+
+Typical use cases:
+
+- **Org-managed credentials** — one Gmail / Salesforce / GitHub connection that every user in your app can call against, without each user having to authenticate separately.
+- **Background agents acting on behalf of multiple users** — the agent runs as a single service account but executes work for many `userId`s.
+- **Team mailboxes** — `support@` or `sales@` accounts where any teammate can send/read mail through your app.
+
+## SHARED vs PRIVATE
+
+| | PRIVATE (default) | SHARED |
+|---|---|---|
+| **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` |
+
+<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.
+</Callout>
+
+## 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).
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+# Create a SHARED Gmail connection that any userId can use,
+# except `user_bob`.
+connection_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"],
+ },
+)
+print(connection_request.redirect_url)
+
+# Have user_admin complete the OAuth flow at the redirect URL,
+# then wait for the connection to become ACTIVE.
+connected = connection_request.wait_for_connection()
+print(f"Shared connection ready: {connected.id}")
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+// Create a SHARED Gmail connection that any userId can use,
+// except `user_bob`.
+const connectionRequest = await composio.connectedAccounts.link(
+ "user_admin",
+ "ac_gmail_shared",
+ {
+ accountType: "SHARED",
+ aclConfigForShared: {
+ allowAllUsers: true,
+ notAllowedUserIds: ["user_bob"],
+ },
+ },
+);
+console.log(connectionRequest.redirectUrl);
+
+// Have user_admin complete the OAuth flow at the redirect URL,
+// then wait for the connection to become ACTIVE.
+const connected = await connectionRequest.waitForConnection();
+console.log(`Shared connection ready: ${connected.id}`);
+```
+ </Tab>
+</Tabs>
+
+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`.
+</Callout>
+
+## ACL resolution rule
+
+When a non-creator `userId` attempts to use a SHARED connection, the ACL is evaluated in this order:
+
+1. `userId` ∈ `notAllowedUserIds` → **DENY**
+2. `allowAllUsers === true` → **ALLOW**
+3. `userId` ∈ `allowedUserIds` → **ALLOW**
+4. otherwise → **DENY** *(deny-by-default)*
+
+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`.
+
+The creator can always use their own connection — the ACL only governs other `userId`s.
+
+### Common ACL patterns
+
+| Goal | Configuration |
+|---|---|
+| **Only the creator** (default) | `{}` (or omit `aclConfigForShared`) |
+| **Allow every `userId`** | `{ allowAllUsers: true }` |
+| **Targeted allow list** | `{ allowedUserIds: ["user_alice", "user_bob"] }` |
+| **Everyone except a few users** | `{ allowAllUsers: true, notAllowedUserIds: ["user_bob"] }` |
+| **Combined: open + targeted deny** | `{ allowAllUsers: true, notAllowedUserIds: ["user_bob"], allowedUserIds: ["user_alice"] }` — Bob still denied (deny wins) |
+
+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.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+# Open access to everyone.
+composio.connected_accounts.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(
+ "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(
+ "ca_gmail_shared",
+ allowed_user_ids=[],
+)
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+// Open access to everyone.
+await composio.connectedAccounts.updateAcl("ca_gmail_shared", {
+ allowAllUsers: true,
+});
+
+// Add a targeted allow list (without touching the wildcard or deny list).
+await composio.connectedAccounts.updateAcl("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", {
+ allowedUserIds: [],
+});
+```
+ </Tab>
+</Tabs>
+
+<Callout type="warn">
+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.
+</Callout>
+
+ACL writes are restricted to the connection's creator or an API key caller. Other callers receive a permission error.
+
+## Using a shared connection
+
+### In a tool-router session
+
+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.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+# user_alice starts a session that pins the shared Gmail connection.
+# Gmail tools loaded from this session will resolve to that connection
+# even though user_alice did not create it.
+session = composio.create(
+ user_id="user_alice",
+ connected_accounts={
+ "gmail": ["ca_gmail_shared"],
+ },
+)
+
+tools = session.tools()
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+// user_alice starts a session that pins the shared Gmail connection.
+// Gmail tools loaded from this session will resolve to that connection
+// even though user_alice did not create it.
+const session = await composio.create("user_alice", {
+ connectedAccounts: {
+ gmail: ["ca_gmail_shared"],
+ },
+});
+
+const tools = await session.tools();
+```
+ </Tab>
+</Tabs>
+
+<Callout type="info">
+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.
+</Callout>
+
+### Direct execution
+
+Pass the SHARED connection's ID explicitly via `connectedAccountId`:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+result = composio.tools.execute(
+ slug="GMAIL_SEND_EMAIL",
+ user_id="user_alice",
+ connected_account_id="ca_gmail_shared",
+ arguments={"to": "[email protected]", "subject": "hi", "body": "..."},
+)
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+const result = await composio.tools.execute("GMAIL_SEND_EMAIL", {
+ userId: "user_alice",
+ connectedAccountId: "ca_gmail_shared",
+ arguments: { to: "[email protected]", subject: "hi", body: "..." },
+});
+```
+ </Tab>
+</Tabs>
+
+If `user_alice` isn't permitted by the connection's ACL, the call raises `ComposioSharedAccessDeniedError`.
+
+## 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.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+account = 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")
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { 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");
+}
+```
+ </Tab>
+</Tabs>
+
+## Error handling
+
+| Error | When |
+|---|---|
+| `ComposioAclOnlyForSharedError` (400) | ACL fields sent on a PRIVATE connection (at create or update time). |
+| `ComposioSharedAccessDeniedError` (403) | Direct execute with a SHARED `connectedAccountId` that the requesting `userId` isn't permitted to use. |
+| `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. |
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+from composio import exceptions
+
+try:
+ composio.connected_accounts.update_acl(
+ "ca_private_gmail", # this connection is PRIVATE
+ allow_all_users=True,
+ )
+except exceptions.ComposioAclOnlyForSharedError as e:
+ print(f"ACL only applies to SHARED connections: {e}")
+
+try:
+ composio.tools.execute(
+ slug="GMAIL_SEND_EMAIL",
+ user_id="user_bob", # not on the allow list
+ connected_account_id="ca_gmail_shared",
+ arguments={...},
+ )
+except exceptions.ComposioSharedAccessDeniedError as e:
+ print(f"Access denied: {e}")
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+import {
+ ComposioAclOnlyForSharedError,
+ ComposioSharedAccessDeniedError,
+} from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+try {
+ await composio.connectedAccounts.updateAcl("ca_private_gmail", {
+ allowAllUsers: true,
+ });
+} catch (error) {
+ if (error instanceof ComposioAclOnlyForSharedError) {
+ console.log(`ACL only applies to SHARED connections: ${error.message}`);
+ }
+}
+
+try {
+ await composio.tools.execute("GMAIL_SEND_EMAIL", {
+ userId: "user_bob", // not on the allow list
+ connectedAccountId: "ca_gmail_shared",
+ arguments: { /* ... */ },
+ });
+} catch (error) {
+ if (error instanceof ComposioSharedAccessDeniedError) {
+ console.log(`Access denied: ${error.message}`);
+ }
+}
+```
+ </Tab>
+</Tabs>
+
+## What to read next
+
+<Cards>
+ <Card icon={<Database />} title="Connected accounts" href="/docs/auth-configuration/connected-accounts" description="Manage and monitor user connections to toolkits" />
+ <Card icon={<Plug />} title="Managing multiple connected accounts" href="/docs/managing-multiple-connected-accounts" description="Pin specific accounts into a session at runtime" />
+ <Card icon={<Wrench />} title="Configuring sessions" href="/docs/configuring-sessions" description="Session config — custom auth configs, pinned connections, multi-account" />
+</Cards>
diff --git a/docs/package.json b/docs/package.json
index feccf08d5..3585453aa 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -44,7 +44,7 @@
"@anthropic-ai/sdk": "^0.71.2",
"@composio/anthropic": "^0.5.5",
"@composio/claude-agent-sdk": "^0.6.3",
- "@composio/core": "^0.9.0",
+ "@composio/core": "^0.9.1",
"@composio/google": "^0.5.5",
"@composio/langchain": "^0.5.5",
"@composio/llamaindex": "^0.5.5",