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: add Shared Connections page under Authentication
venkat82c31ffce2e414
diff --git a/docs/bun.lock b/docs/bun.lockindex 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.jsonindex 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.mdxnew file mode 100644index 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.jsonindex 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",