userID that created it can use it. A SHARED connection can be reached by other userIDs, subject to a per-connection access control list (ACL).
You use a shared connection by pinning it into a session: 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
userIDs. - Team mailboxes.
support@orsales@accounts where any teammate can send and read mail through your app.
SHARED vs PRIVATE
Creating a SHARED connection
Pass anexperimental 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).
- Python
- TypeScript
- API
connectedAccountId (ca_...) is the ID you’ll pin into other users’ sessions.
Using a shared connection
Pin the SHARED connection into a session throughconnectedAccounts. 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.
- Python
- TypeScript
- API
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-creatoruserID attempts to use a SHARED connection, the ACL is evaluated in this order:
userId∈notAllowedUserIds→ DENYallowAllUsers === true→ ALLOWuserId∈allowedUserIds→ ALLOW- otherwise → DENY (deny-by-default)
allowAllUsers: true and naming the exceptions in notAllowedUserIds.
The creator can always use their own connection. The ACL only governs other userIDs.
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).
Each list accepts up to 1000 entries; each
userID is 1..256 characters.
Updating the ACL
CallupdateAcl() 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.
- Python
- TypeScript
- API
Listing SHARED connections
By defaultlist() returns PRIVATE only, so shared accounts must be requested explicitly. Pass an account_type (Python) or accountType (TypeScript) filter to scope the query.
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.
- Python
- TypeScript
- API
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.
- Python
- TypeScript
- API
Error handling
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).