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(connected-accounts): sanitize public docstrings — remove internal references

venkat82eba561f771bd
diff --git a/.changeset/connected-accounts-acl.md b/.changeset/connected-accounts-acl.md
index d580488b7..b963e8818 100644
--- a/.changeset/connected-accounts-acl.md
+++ b/.changeset/connected-accounts-acl.md
@@ -2,14 +2,12 @@
'@composio/core': minor
---
-Add `accountType` and per-user ACL support for SHARED connected accounts (Hermes #9860, #9882, #9902).
+Add `accountType` and per-user ACL support for SHARED connected accounts.
-Surfaces three Apollo-side features that previously had no SDK wrappers:
-
-- **`accountType` on create**: `composio.connectedAccounts.link(userId, authConfigId, { accountType: 'SHARED' })` creates a SHARED connection. Default remains `PRIVATE`. SHARED is reachable from a tool-router session by other users in the project, but only when explicitly pinned and only when the requesting `userId` passes the connection's ACL.
+- **`accountType` on create**: `composio.connectedAccounts.link(userId, authConfigId, { accountType: 'SHARED' })` creates a SHARED connection. Default remains `PRIVATE`. A SHARED connection can be used by other `userId`s, but only when the connection is explicitly pinned in a tool-router session's config and only when the requesting `userId` passes the connection's ACL.
- **`accountType` on retrieve**: `get()` and `list()` responses now include `accountType` (`'PRIVATE' | 'SHARED'`).
-- **`aclConfigForShared` on create + retrieve**: per-user ACL block — `{ allowAllUsers, allowedUserIds, notAllowedUserIds }`. On responses the whole block is `undefined` for non-creator/non-API-key callers (the backend strips it), so callers can distinguish *"I can't see the ACL"* from *"ACL is the default deny-by-default state"*.
-- **`updateAcl()` method** (new): `composio.connectedAccounts.updateAcl(nanoid, { allowAllUsers, allowedUserIds, notAllowedUserIds })` writes the ACL via `PATCH /connected_accounts/{id}` (the SDK serialises to the wire's `acl_config_for_shared` block). Backend rejects ACL writes on PRIVATE rows with `ComposioAclOnlyForSharedError` (400). PATCH semantics — omit a field to leave it unchanged; pass an empty array to clear an allow/deny list. At least one field required.
+- **`aclConfigForShared` on create + retrieve**: per-user ACL block — `{ allowAllUsers, allowedUserIds, notAllowedUserIds }`. On responses the field is `undefined` when the caller isn't authorised to see the ACL, so callers can distinguish *"I can't see the ACL"* from *"ACL is the default deny-by-default state"*.
+- **`updateAcl()` method** (new): `composio.connectedAccounts.updateAcl(nanoid, { allowAllUsers, allowedUserIds, notAllowedUserIds })` writes the ACL via `PATCH`. PATCH semantics — omit a field to leave it unchanged; pass an empty array to clear an allow/deny list. At least one field required. Calling on a PRIVATE connection raises `ComposioAclOnlyForSharedError` (400).
- **`ToolRouterSession.authorize()` options gain `accountType` + `aclConfigForShared`**, so a SHARED connection with an ACL can be created in one call from inside a tool-router session.
ACL resolution rule (deny wins):
@@ -19,14 +17,14 @@ ACL resolution rule (deny wins):
3. requesting `userId` ∈ `allowedUserIds` → ALLOW
4. otherwise → DENY (deny-by-default)
-Backend caps: each ACL list ≤1000 entries; each `userId` 1..256 chars. The SDK enforces these caps via Zod at the input boundary.
+Limits: each ACL list accepts up to 1000 entries; each `userId` is 1..256 characters. The SDK enforces these caps at the input boundary.
New error classes:
- `ComposioSharedAccessDeniedError` (403) — surfaces from direct `connectedAccountId` execution paths when the requesting user fails the ACL.
-- `ComposioAclOnlyForSharedError` (400) — sent ACL fields on a PRIVATE row.
+- `ComposioAclOnlyForSharedError` (400) — ACL fields sent on a PRIVATE connection.
- `ComposioSharedConnectionNotAccessibleError` (400) — tool-router session create / PATCH with a pinned SHARED connection the session user cannot use.
No breaking changes. Existing `link()` callers without the new options get a `PRIVATE` connection exactly as today; existing `get()` / `list()` callers see new optional fields.
-The Python SDK mirror ships in a separate PR — same wire contract, same release train.
+The Python SDK mirror ships in a separate PR.
diff --git a/ts/packages/core/src/errors/ConnectedAccountsErrors.ts b/ts/packages/core/src/errors/ConnectedAccountsErrors.ts
index 48cd19d78..3d5e92d3a 100644
--- a/ts/packages/core/src/errors/ConnectedAccountsErrors.ts
+++ b/ts/packages/core/src/errors/ConnectedAccountsErrors.ts
@@ -60,12 +60,9 @@ export class ComposioFailedToCreateConnectedAccountLink extends ComposioError {
* Thrown when a tool execution attempts to use a SHARED connected account
* but the requesting `userId` is not allowed by the connection's ACL.
*
- * Surfaces from the matching layer when a SHARED connection is reached
- * directly (e.g. via `composio.tools.execute(slug, { connectedAccountId })`)
- * without going through a tool-router session that already pre-flighted the
- * ACL at session-create time.
- *
- * Backend response: 403 with code `ConnectedAccount_SharedAccessDenied`.
+ * Surfaces when a SHARED connection is reached directly (e.g. via
+ * `composio.tools.execute(slug, { connectedAccountId })`) without going
+ * through a tool-router session.
*/
export class ComposioSharedAccessDeniedError extends ComposioError {
constructor(
@@ -86,11 +83,8 @@ export class ComposioSharedAccessDeniedError extends ComposioError {
/**
* Thrown when ACL fields (`allowAllUsers`, `allowedUserIds`,
- * `notAllowedUserIds`) are sent on a `PRIVATE` connection — at create time
- * or via PATCH. ACL is only meaningful for `SHARED` connections; the
- * matching layer never reads it for PRIVATE.
- *
- * Backend response: 400 with code `ConnectedAccount_AclOnlyForShared`.
+ * `notAllowedUserIds`) are sent on a `PRIVATE` connection — at create
+ * time or via PATCH. ACL is only meaningful for `SHARED` connections.
*/
export class ComposioAclOnlyForSharedError extends ComposioError {
constructor(
@@ -111,10 +105,8 @@ export class ComposioAclOnlyForSharedError extends ComposioError {
/**
* Thrown by tool-router session create / PATCH when the session's `userId`
- * cannot use a pinned SHARED connection — caught at session-create time so
- * the session never enters a state that 4xxs mid-execution.
- *
- * Backend response: 400 with code `ToolRouterV2_SharedConnectionNotAccessible`.
+ * cannot use a pinned SHARED connection — caught at session-create time
+ * so the session never enters a state that fails mid-execution.
*/
export class ComposioSharedConnectionNotAccessibleError extends ComposioError {
constructor(
diff --git a/ts/packages/core/src/models/ConnectedAccounts.ts b/ts/packages/core/src/models/ConnectedAccounts.ts
index 3c34fe703..c3e932f89 100644
--- a/ts/packages/core/src/models/ConnectedAccounts.ts
+++ b/ts/packages/core/src/models/ConnectedAccounts.ts
@@ -57,12 +57,12 @@ import { ConnectionData } from '../types/connectedAccountAuthStates.types';
let _legacyInitiateWarningEmitted = false;
/**
- * Serialise the SDK's `aclConfigForShared` (camelCase, top-level optional)
- * to the wire's `acl_config_for_shared` block. Returns `undefined` when the
- * caller didn't pass anything (PATCH-style "don't touch ACL"); returns
- * `{}` when the caller passed an explicit empty object (the backend treats
- * both the same way today — deny-by-default — but the explicit form is
- * preserved so the intent is visible in network traces).
+ * Serialise the SDK's `aclConfigForShared` (camelCase) to the wire's
+ * `acl_config_for_shared` block. Returns `undefined` when the caller
+ * didn't pass anything (PATCH-style "don't touch ACL"); returns `{}`
+ * when the caller passed an explicit empty object — both mean
+ * deny-by-default, but the explicit form preserves the caller's intent
+ * in network traces.
*/
function serializeAclConfigForWire(
acl:
@@ -419,9 +419,8 @@ export class ConnectedAccounts {
);
return connectionRequest;
} catch (error) {
- // Backend rejects ACL fields on PRIVATE connections with a 400 +
- // `ConnectedAccount_AclOnlyForShared`. Surface it as a typed error so
- // callers can `instanceof` instead of grepping messages.
+ // The server rejects ACL on PRIVATE connections — surface that as a
+ // typed error so callers can `instanceof` instead of grepping messages.
if (
error instanceof BadRequestError &&
typeof error.message === 'string' &&
@@ -616,11 +615,9 @@ export class ConnectedAccounts {
}
/**
- * Enable or disable a connected account (wraps the `/status` endpoint
- * — accepts only `{ enabled: boolean }` despite the historical JSDoc
- * mentioning "alias and/or credentials"). For ACL writes on SHARED
- * connections, see {@link updateAcl}. Alias / credential PATCH isn't
- * surfaced on the SDK yet.
+ * Enable or disable a connected account. Accepts `{ enabled: boolean }`.
+ *
+ * For ACL writes on SHARED connections, see {@link updateAcl}.
*
* @param {string} nanoid - The unique identifier of the connected account
* @param {UpdateConnectedAccountParams} params - The update parameters
@@ -649,23 +646,23 @@ export class ConnectedAccounts {
/**
* Update the per-user ACL on a SHARED connected account.
*
- * Only meaningful for SHARED connections — the backend rejects ACL writes
- * on PRIVATE rows with `ComposioAclOnlyForSharedError` (400). Auth gate is
- * creator-or-API-key (a non-creator project member updating an alias on a
- * SHARED row still works via {@link update}, but ACL writes do not).
+ * Only meaningful for SHARED connections — calling this on a PRIVATE
+ * connection raises `ComposioAclOnlyForSharedError` (400). ACL writes
+ * require the connection's creator or an API key; alias edits via
+ * {@link update} are governed separately.
*
* PATCH semantics: omit a field to leave it unchanged; pass an empty array
* to clear an allow/deny list. At least one field must be provided.
*
* Resolution rule (deny wins):
- * 1. requesting userId in `notAllowedUserIds` → DENY
- * 2. `allowAllUsers === true` → ALLOW
- * 3. requesting userId in `allowedUserIds` → ALLOW
- * 4. otherwise → DENY
+ * 1. requesting `userId` in `notAllowedUserIds` → DENY
+ * 2. `allowAllUsers === true` → ALLOW
+ * 3. requesting `userId` in `allowedUserIds` → ALLOW
+ * 4. otherwise → DENY
*
* @example
* ```typescript
- * // Open access to everyone in the project
+ * // Allow every userId to use this connection
* await composio.connectedAccounts.updateAcl('ca_abc', { allowAllUsers: true });
*
* // Everyone except a specific user
@@ -714,8 +711,8 @@ export class ConnectedAccounts {
try {
return await this.client.connectedAccounts.patch(nanoid, body);
} catch (error) {
- // Same `AclOnlyForShared` 400 the create path can hit — backend
- // rejects ACL writes on a PRIVATE row at PATCH-time too.
+ // Same ACL-on-PRIVATE rejection the create path can hit — surface
+ // it as a typed error.
if (
error instanceof BadRequestError &&
typeof error.message === 'string' &&
diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.ts
index c50982977..e3dd6343b 100644
--- a/ts/packages/core/src/models/ToolRouterSession.ts
+++ b/ts/packages/core/src/models/ToolRouterSession.ts
@@ -76,9 +76,9 @@ export const DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX =
* Options accepted by {@link ToolRouterSession.authorize}.
*
* Validated at the SDK boundary so callers get clear `ValidationError`s for
- * oversized ACL lists or invalid user IDs — same Zod caps as the equivalent
+ * oversized ACL lists or invalid `userId`s — same caps as the equivalent
* `composio.connectedAccounts.link()` path (≤1000 entries per list, each
- * user_id 1..256 chars). Caught Bugbot review.
+ * `userId` 1..256 characters).
*/
const AuthorizeOptionsSchema = z.object({
callbackUrl: z.string().optional(),
@@ -327,15 +327,14 @@ export class ToolRouterSession<
* Initiate an authorization flow for a toolkit.
* Returns a ConnectionRequest with a redirect URL for the user.
*
- * `accountType` and `aclConfigForShared` (Hermes #9860, #9902) let the
- * caller create a SHARED connection with a per-user ACL in one flow.
- * Default behaviour (omit both) creates a PRIVATE connection.
+ * Use `accountType` and `aclConfigForShared` to create a SHARED connection
+ * with a per-user ACL in one flow. Default behaviour (omit both) creates
+ * a PRIVATE connection.
*
- * `aclConfigForShared` is validated through `ConnectedAccountAclConfigSchema`
- * — same Zod caps as `composio.connectedAccounts.link()` (≤1000 entries
- * per list, each user_id 1..256 chars). Invalid input throws
- * `ValidationError` at the SDK boundary instead of hitting an opaque
- * backend 400.
+ * `aclConfigForShared` is validated against the same caps as
+ * `composio.connectedAccounts.link()` (≤1000 entries per list, each
+ * `userId` 1..256 characters). Invalid input throws `ValidationError`
+ * at the SDK boundary.
*/
async authorize(
toolkit: string,
@@ -379,9 +378,8 @@ export class ToolRouterSession<
try {
response = await this.client.toolRouter.session.link(this.sessionId, body);
} catch (error) {
- // Backend rejects ACL fields on PRIVATE connections with a 400 +
- // `ConnectedAccount_AclOnlyForShared`. Surface it as a typed error
- // mirroring `composio.connectedAccounts.link()`.
+ // The server rejects ACL on PRIVATE connections — surface that as a
+ // typed error mirroring `composio.connectedAccounts.link()`.
if (
error instanceof BadRequestError &&
typeof error.message === 'string' &&
diff --git a/ts/packages/core/src/types/connectedAccounts.types.ts b/ts/packages/core/src/types/connectedAccounts.types.ts
index bad43af21..745214568 100644
--- a/ts/packages/core/src/types/connectedAccounts.types.ts
+++ b/ts/packages/core/src/types/connectedAccounts.types.ts
@@ -31,11 +31,11 @@ export type ConnectedAccountStatusEnum = z.infer<typeof ConnectedAccountStatusSc
* Sharing model for a connected account.
*
* - `PRIVATE` (default): only the owning `userId` can use the connection.
- * - `SHARED`: reachable from a tool-router session by other users in the
- * project, but only when explicitly pinned in the session config and only
- * when the requesting `userId` passes the connection's ACL (see
- * `allowAllUsers` / `allowedUserIds` / `notAllowedUserIds`). Set at create
- * time only — cannot be changed later.
+ * - `SHARED`: can be used by other `userId`s, but only when the connection
+ * is explicitly pinned in a tool-router session's config and only when
+ * the requesting `userId` passes the connection's ACL (see
+ * `allowAllUsers` / `allowedUserIds` / `notAllowedUserIds`). Set at
+ * creation time only — cannot be changed later.
*/
export const ConnectedAccountTypes = {
PRIVATE: 'PRIVATE',
@@ -49,24 +49,26 @@ export type ConnectedAccountType =
(typeof ConnectedAccountTypes)[keyof typeof ConnectedAccountTypes];
/**
- * Per-user access control for a SHARED connected account. Inert for PRIVATE.
+ * Per-user access control for a SHARED connected account. Ignored for
+ * PRIVATE.
*
- * On the wire this lives under `acl_config_for_shared` — a single JSONB
- * column on `connected_accounts`. The SDK exposes the inner shape as
- * `aclConfigForShared` on inputs and responses (omit the block to mean
- * "don't touch ACL" on create / PATCH; absence on a response means the
- * caller isn't allowed to see the ACL).
+ * Pass `aclConfigForShared` on create / PATCH to grant access; omit it
+ * to leave the ACL unchanged (on PATCH) or to keep the default
+ * deny-by-default state (on create). On responses, the field is
+ * `undefined` when the caller isn't authorised to see the ACL —
+ * distinguish that from an empty/default state explicitly.
*
* Resolution rule (deny wins):
- * 1. requesting userId in `notAllowedUserIds` → DENY
- * 2. `allowAllUsers === true` → ALLOW
- * 3. requesting userId in `allowedUserIds` → ALLOW
- * 4. otherwise → DENY (deny-by-default)
+ * 1. requesting `userId` in `notAllowedUserIds` → DENY
+ * 2. `allowAllUsers === true` → ALLOW
+ * 3. requesting `userId` in `allowedUserIds` → ALLOW
+ * 4. otherwise → DENY (deny-by-default)
*
- * Default state (block omitted or `{}`) means only the connection's creator
- * can use it. The creator must grant access explicitly.
+ * Default state (block omitted or `{}`) means only the connection's
+ * creator can use it. The creator must grant access explicitly.
*
- * Backend caps: each list ≤1000 entries; each user_id 1..256 chars.
+ * Limits: each list accepts up to 1000 entries; each `userId` is
+ * 1..256 characters.
*/
const ACL_LIST_MAX_LENGTH = 1000;
const ACL_USER_ID_MAX_LENGTH = 256;
@@ -76,24 +78,24 @@ export const ConnectedAccountAclConfigSchema = z.object({
allowAllUsers: z
.boolean()
.optional()
- .describe('Wildcard "any user_id in the project" allow toggle. Default false.'),
+ .describe('When true, any `userId` may use this SHARED connection (subject to the deny list). Default false.'),
allowedUserIds: z
.array(aclUserIdString)
.max(ACL_LIST_MAX_LENGTH)
.optional()
- .describe('Explicit allow list (developer-assigned user_id strings). Default [].'),
+ .describe('Explicit list of `userId` strings allowed to use this SHARED connection. Default [].'),
notAllowedUserIds: z
.array(aclUserIdString)
.max(ACL_LIST_MAX_LENGTH)
.optional()
- .describe('Explicit deny list. Wins over allow on conflict. Default [].'),
+ .describe('Explicit list of `userId` strings denied access. Wins over allow on conflict. Default [].'),
});
export type ConnectedAccountAclConfig = z.infer<typeof ConnectedAccountAclConfigSchema>;
/**
- * Resolved ACL as it appears on responses (creator / API-key callers).
- * All three fields are populated when the block is visible; the block
- * itself is absent for non-creator cookie callers.
+ * Resolved ACL as it appears on responses. All three fields are populated
+ * when the field is visible; the field itself is `undefined` for callers
+ * not authorised to see it.
*/
export const ConnectedAccountAclConfigResponseSchema = z.object({
allowAllUsers: z.boolean(),
@@ -211,11 +213,11 @@ export const ConnectedAccountRetrieveResponseSchema: z.ZodType<{
createdAt: z.string(),
updatedAt: z.string(),
accountType: ConnectedAccountTypeSchema.optional(),
- // `acl_config_for_shared` is only present on responses when the caller is
- // the connection's creator or is using a project/org API key. Non-creator
- // cookie callers see the row without this block — left as `undefined`
- // here so callers can distinguish "I can't see the ACL" from "ACL is the
- // default deny-by-default state".
+ // `aclConfigForShared` is only present on the response when the caller
+ // is authorised to see the ACL — otherwise the block is absent and the
+ // field is `undefined`. Callers can distinguish "I can't see the ACL"
+ // from "ACL is the default deny-by-default state" by checking for the
+ // presence of the field.
aclConfigForShared: ConnectedAccountAclConfigResponseSchema.optional(),
});
@@ -292,11 +294,11 @@ export const CreateConnectedAccountLinkOptionsSchema = z.object({
*/
allowMultiple: z.boolean().optional(),
/**
- * Sharing model for the new connection. `PRIVATE` (default) is usable only by
- * the owning `userId`. `SHARED` is reachable from a tool-router session by
- * other users in the project — but only when explicitly pinned and only when
- * the requesting `userId` passes the connection's ACL. Set at create time
- * only.
+ * Sharing model for the new connection. `PRIVATE` (default) is usable only
+ * by the owning `userId`. `SHARED` can be used by other `userId`s — but
+ * only when the connection is explicitly pinned in a tool-router session's
+ * config and only when the requesting `userId` passes the connection's
+ * ACL. Set at creation time only.
*/
accountType: ConnectedAccountTypeSchema.optional(),
/**
diff --git a/ts/packages/core/src/utils/transformers/connectedAccounts.ts b/ts/packages/core/src/utils/transformers/connectedAccounts.ts
index c831535ca..c4afbd897 100644
--- a/ts/packages/core/src/utils/transformers/connectedAccounts.ts
+++ b/ts/packages/core/src/utils/transformers/connectedAccounts.ts
@@ -18,15 +18,6 @@ type RawConnectedAccountResponseWithLabels = (
) & {
word_id?: string | null;
alias?: string | null;
- // account_type / acl_config_for_shared are added by Hermes #9860, #9882,
- // and the merged #9902. Cast lives here until @composio/client regenerates
- // against a backend spec that contains them.
- account_type?: 'PRIVATE' | 'SHARED';
- acl_config_for_shared?: {
- allow_all_users: boolean;
- allowed_user_ids: string[];
- not_allowed_user_ids: string[];
- };
};
/**
@@ -80,11 +71,11 @@ export function transformConnectedAccountResponse(
updatedAt: response.updated_at,
testRequestEndpoint: response.test_request_endpoint,
accountType: responseWithLabels.account_type,
- // `acl_config_for_shared` is conditionally visible — backend strips
- // the whole block for non-creator/non-API-key callers. Forward
- // `undefined` when absent rather than synthesising defaults, so
- // callers can distinguish "I can't see the ACL" from "ACL is the
- // default deny-by-default state".
+ // `acl_config_for_shared` is conditionally visible — the field is
+ // absent when the caller isn't authorised to see it. Forward
+ // `undefined` rather than synthesising defaults so callers can
+ // distinguish "I can't see the ACL" from "ACL is the default
+ // deny-by-default state".
aclConfigForShared: responseWithLabels.acl_config_for_shared
? {
allowAllUsers: responseWithLabels.acl_config_for_shared.allow_all_users,
diff --git a/ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts b/ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts
index 45ab3c57f..98c22838e 100644
--- a/ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts
+++ b/ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts
@@ -1521,7 +1521,7 @@ describe('ConnectedAccounts', () => {
});
});
- describe('link with accountType + ACL (Hermes #9860, #9902)', () => {
+ describe('link with accountType + ACL', () => {
beforeEach(() => {
extendedMockClient.connectedAccounts.list.mockResolvedValue({
items: [],