> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Shared connections

> Make a connected account usable by multiple users with a per-user access control list

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).

You use a shared connection by [pinning it into a session](#using-a-shared-connection): the session's `userID` doesn't own the connection, but the pin makes it available. A SHARED connection is never resolved implicitly, so a session reaches one only when you pin it explicitly.

Typical use cases:

* **Org-managed credentials.** One Gmail, Salesforce, or 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 and read mail through your app.

## SHARED vs PRIVATE

| | PRIVATE (default) | SHARED |
| - | - | - |
| **Who can use it** | Only the owning `userID` | The creator plus 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 session |
| **ACL fields** | Ignored | `allowAllUsers`, `allowedUserIds`, `notAllowedUserIds` (inside the `experimental` block) |

## Creating a SHARED connection

Pass an `experimental` block to `link()` (`accountType` in TypeScript, `account_type` in Python) set to `"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).

> [tab] Python
>
> ```python theme={null}
> # 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",
>     experimental={
>         "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] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> // Create a SHARED Gmail connection that any userId can use,
> // except `user_bob`.
> const connectionRequest = await composio.connectedAccounts.link(
>   "user_admin",
>   "ac_gmail_shared",
>   {
>     experimental: {
>       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] API
>
> ```bash theme={null}
> # Create a SHARED Gmail connection that any userId can use,
> # except `user_bob`. Send user_admin to the returned redirect_url.
> curl -X POST https://backend.composio.dev/api/v3.1/connected_accounts/link \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_admin",
>     "auth_config_id": "ac_gmail_shared",
>     "experimental": {
>       "account_type": "SHARED",
>       "acl_config_for_shared": {
>         "allow_all_users": true,
>         "not_allowed_user_ids": ["user_bob"]
>       }
>     }
>   }'
> ```

The returned `connectedAccountId` (`ca_...`) is the ID you'll pin into other users' sessions.

> [!WARNING]
>
> ACL fields are only valid on SHARED connections. Sending an `experimental.acl_config_for_shared` block on a PRIVATE connection raises `ComposioAclOnlyForSharedError`.

## Using a shared connection

Pin the SHARED connection into a session through `connectedAccounts`. The session belongs to a *different* `userID` than the creator, and the pin is what makes the SHARED connection visible to that session.

The session config itself is **not** experimental. You pin the connection by ID exactly as you would a PRIVATE one.

> [tab] Python
>
> ```python theme={null}
> # 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] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> // 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] API
>
> ```bash theme={null}
> # user_alice starts a session that pins the shared Gmail connection.
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_alice", "connected_accounts": {"gmail": ["ca_gmail_shared"]}}'
> ```

> [!NOTE]
>
> 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.

## 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

The table below shows the inner shape of the ACL block (`aclConfigForShared` in TypeScript, `acl_config_for_shared` in Python). Wrap it inside the `experimental` block at the call site. Field names are camelCase in the TypeScript samples; Python callers translate to snake\_case (`allow_all_users`, `allowed_user_ids`, `not_allowed_user_ids`).

| Goal | ACL block |
| - | - |
| **Only the creator** (default) | `{}` (or omit the block) |
| **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

Call `updateAcl()` on the connected accounts namespace to change access after creation. It follows PATCH semantics: pass only the fields you want to change, omit a field to leave it unchanged, and pass an empty array to clear an allow or deny list.

> [tab] Python
>
> ```python theme={null}
> # 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] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> // 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] API
>
> ```bash theme={null}
> # Open access to everyone.
> curl -X PATCH https://backend.composio.dev/api/v3.1/connected_accounts/ca_gmail_shared \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"experimental": {"acl_config_for_shared": {"allow_all_users": true}}}'
>
> # Add a targeted allow list (without touching the wildcard or deny list).
> curl -X PATCH https://backend.composio.dev/api/v3.1/connected_accounts/ca_gmail_shared \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"experimental": {"acl_config_for_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).
> curl -X PATCH https://backend.composio.dev/api/v3.1/connected_accounts/ca_gmail_shared \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"experimental": {"acl_config_for_shared": {"allowed_user_ids": []}}}'
> ```

> [!WARNING]
>
> 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.

ACL writes are restricted to the connection's creator or an API key caller. Other callers get a permission error.

## Listing SHARED connections

By default `list()` returns **PRIVATE only**, so shared accounts must be requested explicitly. Pass an `account_type` (Python) or `accountType` (TypeScript) filter to scope the query.

| Value | Returns |
| - | - |
| `'PRIVATE'` *(default when omitted)* | Only PRIVATE connections |
| `'SHARED'` | Only SHARED connections |
| `'ALL'` | PRIVATE + SHARED |

The filter is a flat query param on the wire (`?account_type=...`), so it stays flat in both SDKs, unlike the create and update surfaces, which nest under `experimental`.

> [tab] Python
>
> ```python theme={null}
> # List every SHARED connection the caller has visibility into.
> shared = composio.connected_accounts.list(account_type="SHARED")
>
> for item in shared.items:
>     print(item.id, item.toolkit.slug)
>
> # Scope to a single user's SHARED connections.
> shared_for_alice = composio.connected_accounts.list(
>     account_type="SHARED",
>     user_ids=["user_alice"],
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> // List every SHARED connection the caller has visibility into.
> const shared = await composio.connectedAccounts.list({ accountType: "SHARED" });
>
> for (const item of shared.items) {
>   console.log(item.id, item.toolkit.slug);
> }
>
> // Scope to a single user's SHARED connections.
> const sharedForAlice = await composio.connectedAccounts.list({
>   accountType: "SHARED",
>   userIds: ["user_alice"],
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # List every SHARED connection the caller has visibility into.
> curl -X GET "https://backend.composio.dev/api/v3.1/connected_accounts?account_type=SHARED" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
>
> # Scope to a single user's SHARED connections.
> curl -X GET "https://backend.composio.dev/api/v3.1/connected_accounts?account_type=SHARED&user_ids=user_alice" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

## Inspecting the ACL

`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.

> [tab] Python
>
> ```python theme={null}
> account = composio.connected_accounts.get("ca_gmail_shared")
>
> if account.experimental:
>     print(f"Type: {account.experimental.account_type}")  # "PRIVATE" or "SHARED"
>
>     if account.experimental.acl_config_for_shared:
>         acl = account.experimental.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] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const account = await composio.connectedAccounts.get("ca_gmail_shared");
>
> if (account.experimental) {
>   console.log("Type:", account.experimental.accountType);  // "PRIVATE" or "SHARED"
>
>   if (account.experimental.aclConfigForShared) {
>     const acl = account.experimental.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] API
>
> ```bash theme={null}
> # experimental.account_type is "PRIVATE" or "SHARED";
> # experimental.acl_config_for_shared is absent when you can't see the ACL.
> curl -s -X GET https://backend.composio.dev/api/v3.1/connected_accounts/ca_gmail_shared \
>   -H "x-api-key: $COMPOSIO_API_KEY" | jq '.experimental'
> ```

## 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 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. |

The access errors are caught the same way as any other Composio exception (`ComposioAclOnlyForSharedError` and `ComposioSharedAccessDeniedError` are exported from `@composio/core`, and live under `composio.exceptions` in Python).

## Next

> [card] [Configuring sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md)
>
> Pin connected accounts, auth configs, and toolkit restrictions into a session
