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.

refactor(connected-accounts): nest ACL under aclConfigForShared, match merged 9902 contract

venkat82752efd886324
diff --git a/.changeset/connected-accounts-acl.md b/.changeset/connected-accounts-acl.md
index 044eb0e74..83bcaf958 100644
--- a/.changeset/connected-accounts-acl.md
+++ b/.changeset/connected-accounts-acl.md
@@ -8,8 +8,9 @@ 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 retrieve**: `get()` and `list()` responses now include `accountType` (`'PRIVATE' | 'SHARED'`).
-- **`updateAcl()` method** (new): `composio.connectedAccounts.updateAcl(nanoid, { allowAllUsers, allowedUserIds, notAllowedUserIds })` writes the per-user ACL on a SHARED connection via `PATCH /connected_accounts/{id}`. 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.
-- **ACL fields on retrieve**: `get()` and `list()` responses expose `allowAllUsers`, `allowedUserIds`, `notAllowedUserIds` when the caller is the connection's creator or is using a project/org API key. Other callers see the row without these fields (left as `undefined` in the SDK shape).
+- **`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.
+- **`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):
@@ -18,12 +19,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.
+
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.
- `ComposioSharedConnectionNotAccessibleError` (400) — tool-router session create / PATCH with a pinned SHARED connection the session user cannot use.
-No breaking changes. Existing `link()` callers without `accountType` get a `PRIVATE` connection exactly as today; existing `get()` / `list()` callers see new optional fields.
+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.
Python SDK gets the matching change in the same release train.
diff --git a/ts/packages/core/src/models/ConnectedAccounts.ts b/ts/packages/core/src/models/ConnectedAccounts.ts
index 93c79ae10..7b50c19d2 100644
--- a/ts/packages/core/src/models/ConnectedAccounts.ts
+++ b/ts/packages/core/src/models/ConnectedAccounts.ts
@@ -52,10 +52,17 @@ import { ConnectionData } from '../types/connectedAccountAuthStates.types';
// warning on every initiate() call.
let _legacyInitiateWarningEmitted = false;
-// Wire-level fields added by Hermes #9860 / #9882 (account_type) and #9902
-// (ACL). Once @composio/client is regenerated against a backend spec that
-// includes these, this local extension can be removed and we can rely on the
-// generated `LinkCreateParams` directly.
+// Wire-level fields added by Hermes #9860 / #9882 (account_type) and
+// merged #9902 (ACL). 9902 nests ACL under a single `acl_config_for_shared`
+// object (single JSONB column under the hood). Once @composio/client is
+// regenerated against the post-9902 backend spec, this local extension can
+// be removed and we can rely on the generated `LinkCreateParams` directly.
+type AclConfigWireShape = {
+ allow_all_users?: boolean;
+ allowed_user_ids?: string[];
+ not_allowed_user_ids?: string[];
+};
+
type LinkCreateBodyWithAcl = ConnectedAccountCreateParamsRaw extends never
? never
: Record<string, unknown> & {
@@ -64,21 +71,40 @@ type LinkCreateBodyWithAcl = ConnectedAccountCreateParamsRaw extends never
alias?: string;
callback_url?: string;
account_type?: 'PRIVATE' | 'SHARED';
- allow_all_users?: boolean;
- allowed_user_ids?: string[];
- not_allowed_user_ids?: string[];
+ acl_config_for_shared?: AclConfigWireShape;
};
-// Wire-level body for PATCH /connected_accounts/{id} with ACL fields
-// (Hermes #9902). Mirrors the same forward-compat pattern as
-// `LinkCreateBodyWithAcl` above.
+// Wire-level body for PATCH /connected_accounts/{id} with ACL.
type ConnectedAccountPatchBodyWithAcl = {
alias?: string;
- allow_all_users?: boolean;
- allowed_user_ids?: string[];
- not_allowed_user_ids?: string[];
+ acl_config_for_shared?: AclConfigWireShape;
};
+/**
+ * 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 (also "no fields to
+ * change", but encodes the explicit intent — the backend treats both the
+ * same way today).
+ */
+function serializeAclConfigForWire(
+ acl:
+ | {
+ allowAllUsers?: boolean;
+ allowedUserIds?: string[];
+ notAllowedUserIds?: string[];
+ }
+ | undefined
+): AclConfigWireShape | undefined {
+ if (acl === undefined) return undefined;
+ return {
+ ...(acl.allowAllUsers !== undefined && { allow_all_users: acl.allowAllUsers }),
+ ...(acl.allowedUserIds !== undefined && { allowed_user_ids: acl.allowedUserIds }),
+ ...(acl.notAllowedUserIds !== undefined && { not_allowed_user_ids: acl.notAllowedUserIds }),
+ };
+}
+
/**
* ConnectedAccounts class
*
@@ -396,17 +422,14 @@ export class ConnectedAccounts {
}
const opts = requestOptions.data;
+ const aclWire = serializeAclConfigForWire(opts.aclConfigForShared);
const body: LinkCreateBodyWithAcl = {
auth_config_id: authConfigId,
user_id: userId,
...(opts.callbackUrl && { callback_url: opts.callbackUrl }),
...(opts.alias != null && { alias: opts.alias }),
...(opts.accountType !== undefined && { account_type: opts.accountType }),
- ...(opts.allowAllUsers !== undefined && { allow_all_users: opts.allowAllUsers }),
- ...(opts.allowedUserIds !== undefined && { allowed_user_ids: opts.allowedUserIds }),
- ...(opts.notAllowedUserIds !== undefined && {
- not_allowed_user_ids: opts.notAllowedUserIds,
- }),
+ ...(aclWire !== undefined && { acl_config_for_shared: aclWire }),
};
try {
@@ -683,18 +706,10 @@ export class ConnectedAccounts {
}
const body: ConnectedAccountPatchBodyWithAcl = {
- ...(parsedParams.data.allowAllUsers !== undefined && {
- allow_all_users: parsedParams.data.allowAllUsers,
- }),
- ...(parsedParams.data.allowedUserIds !== undefined && {
- allowed_user_ids: parsedParams.data.allowedUserIds,
- }),
- ...(parsedParams.data.notAllowedUserIds !== undefined && {
- not_allowed_user_ids: parsedParams.data.notAllowedUserIds,
- }),
+ acl_config_for_shared: serializeAclConfigForWire(parsedParams.data),
};
- // Cast retained until @composio/client adds ACL fields to
+ // Cast retained until @composio/client adds acl_config_for_shared to
// ConnectedAccountPatchParams.
await this.client.connectedAccounts.patch(
nanoid,
diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.ts
index 52c5b9afe..ee12f5356 100644
--- a/ts/packages/core/src/models/ToolRouterSession.ts
+++ b/ts/packages/core/src/models/ToolRouterSession.ts
@@ -26,7 +26,11 @@ import {
import { SessionMetaToolOptions } from '../types/modifiers.types';
import { ConnectionRequest } from '../types/connectionRequest.types';
import { createConnectionRequest } from './ConnectionRequest';
-import { ConnectedAccountStatuses } from '../types/connectedAccounts.types';
+import {
+ ConnectedAccountStatuses,
+ ConnectedAccountType,
+ ConnectedAccountAclConfig,
+} from '../types/connectedAccounts.types';
import { transform } from '../utils/transform';
import { ToolkitConnectionStateSchema } from '../types/toolRouter.types';
import { ValidationError } from '../errors';
@@ -303,16 +307,47 @@ 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.
*/
async authorize(
toolkit: string,
- options?: { callbackUrl?: string; alias?: string }
+ options?: {
+ callbackUrl?: string;
+ alias?: string;
+ accountType?: ConnectedAccountType;
+ aclConfigForShared?: ConnectedAccountAclConfig;
+ }
): Promise<ConnectionRequest> {
- const response = await this.client.toolRouter.session.link(this.sessionId, {
+ const aclWire =
+ options?.aclConfigForShared === undefined
+ ? undefined
+ : {
+ ...(options.aclConfigForShared.allowAllUsers !== undefined && {
+ allow_all_users: options.aclConfigForShared.allowAllUsers,
+ }),
+ ...(options.aclConfigForShared.allowedUserIds !== undefined && {
+ allowed_user_ids: options.aclConfigForShared.allowedUserIds,
+ }),
+ ...(options.aclConfigForShared.notAllowedUserIds !== undefined && {
+ not_allowed_user_ids: options.aclConfigForShared.notAllowedUserIds,
+ }),
+ };
+ // Cast retained until @composio/client adds account_type +
+ // acl_config_for_shared to SessionLinkParams (Hermes #9860 + #9902).
+ const body = {
toolkit,
...(options?.callbackUrl && { callback_url: options.callbackUrl }),
...(options?.alias != null && { alias: options.alias }),
- });
+ ...(options?.accountType !== undefined && { account_type: options.accountType }),
+ ...(aclWire !== undefined && { acl_config_for_shared: aclWire }),
+ };
+ const response = await this.client.toolRouter.session.link(
+ this.sessionId,
+ body as unknown as Parameters<typeof this.client.toolRouter.session.link>[1]
+ );
return createConnectionRequest(
this.client,
diff --git a/ts/packages/core/src/types/connectedAccounts.types.ts b/ts/packages/core/src/types/connectedAccounts.types.ts
index 9f9157fca..be5e9d41f 100644
--- a/ts/packages/core/src/types/connectedAccounts.types.ts
+++ b/ts/packages/core/src/types/connectedAccounts.types.ts
@@ -51,35 +51,58 @@ export type ConnectedAccountType =
/**
* Per-user access control for a SHARED connected account. Inert 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).
+ *
* 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)
*
- * Default state (`allowAllUsers=false`, both arrays empty) 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.
*
- * Lists are capped at 1000 entries each by the backend.
+ * Backend caps: each list ≤1000 entries; each user_id 1..256 chars.
*/
-const ACL_LIST_LIMIT = 1000;
-export const ConnectedAccountAclSchema = z.object({
+const ACL_LIST_MAX_LENGTH = 1000;
+const ACL_USER_ID_MAX_LENGTH = 256;
+const aclUserIdString = z.string().min(1).max(ACL_USER_ID_MAX_LENGTH);
+
+export const ConnectedAccountAclConfigSchema = z.object({
allowAllUsers: z
.boolean()
.optional()
.describe('Wildcard "any user_id in the project" allow toggle. Default false.'),
allowedUserIds: z
- .array(z.string())
- .max(ACL_LIST_LIMIT)
+ .array(aclUserIdString)
+ .max(ACL_LIST_MAX_LENGTH)
.optional()
.describe('Explicit allow list (developer-assigned user_id strings). Default [].'),
notAllowedUserIds: z
- .array(z.string())
- .max(ACL_LIST_LIMIT)
+ .array(aclUserIdString)
+ .max(ACL_LIST_MAX_LENGTH)
.optional()
.describe('Explicit deny list. Wins over allow on conflict. Default [].'),
});
-export type ConnectedAccountAcl = z.infer<typeof ConnectedAccountAclSchema>;
+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.
+ */
+export const ConnectedAccountAclConfigResponseSchema = z.object({
+ allowAllUsers: z.boolean(),
+ allowedUserIds: z.array(z.string()),
+ notAllowedUserIds: z.array(z.string()),
+});
+export type ConnectedAccountAclConfigResponse = z.infer<
+ typeof ConnectedAccountAclConfigResponseSchema
+>;
export const CreateConnectedAccountParamsSchema = z.object({
authConfig: z.object({
@@ -163,9 +186,7 @@ export const ConnectedAccountRetrieveResponseSchema: z.ZodType<{
createdAt: string;
updatedAt: string;
accountType?: ConnectedAccountType;
- allowAllUsers?: boolean;
- allowedUserIds?: string[];
- notAllowedUserIds?: string[];
+ aclConfigForShared?: ConnectedAccountAclConfigResponse;
}> = z.object({
id: z.string(),
authConfig: ConnectedAccountAuthConfigSchema,
@@ -190,12 +211,12 @@ export const ConnectedAccountRetrieveResponseSchema: z.ZodType<{
createdAt: z.string(),
updatedAt: z.string(),
accountType: ConnectedAccountTypeSchema.optional(),
- // ACL fields are only present on responses when the caller is the creator
- // or is using a project/org API key — cookie callers who can use the
- // connection but aren't its creator see the row without these fields.
- allowAllUsers: z.boolean().optional(),
- allowedUserIds: z.array(z.string()).optional(),
- notAllowedUserIds: z.array(z.string()).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: ConnectedAccountAclConfigResponseSchema.optional(),
});
export type ConnectedAccountRetrieveResponse = z.infer<
@@ -279,16 +300,16 @@ export const CreateConnectedAccountLinkOptionsSchema = z.object({
*/
accountType: ConnectedAccountTypeSchema.optional(),
/**
- * ACL for SHARED connections. Ignored when `accountType !== 'SHARED'`; the
- * backend rejects ACL fields on a `PRIVATE` connection with `AclOnlyForShared`.
+ * Per-user ACL for SHARED connections. Only valid when
+ * `accountType === 'SHARED'` — the backend rejects ACL on a PRIVATE
+ * connection with `ComposioAclOnlyForSharedError` (400).
*
- * Default (deny-by-default): only the creator can use the connection. Grant
- * access by setting `allowAllUsers: true` or by listing user IDs in
- * `allowedUserIds`. `notAllowedUserIds` always wins over allow.
+ * Omit the block (or pass `{}`) to keep the deny-by-default state: only the
+ * creator can use the connection. Grant access by setting
+ * `allowAllUsers: true` or listing user IDs in `allowedUserIds`.
+ * `notAllowedUserIds` always wins over allow.
*/
- allowAllUsers: ConnectedAccountAclSchema.shape.allowAllUsers,
- allowedUserIds: ConnectedAccountAclSchema.shape.allowedUserIds,
- notAllowedUserIds: ConnectedAccountAclSchema.shape.notAllowedUserIds,
+ aclConfigForShared: ConnectedAccountAclConfigSchema.optional(),
});
export type CreateConnectedAccountLinkOptions = z.infer<
typeof CreateConnectedAccountLinkOptionsSchema
@@ -315,16 +336,18 @@ export const UpdateConnectedAccountParamsSchema = z.object({
});
/**
- * Params for `composio.connectedAccounts.updateAcl()`.
+ * Params for `composio.connectedAccounts.updateAcl()`. Mirrors the inner
+ * shape of the wire's `acl_config_for_shared` block — the SDK adds the
+ * outer nesting at the boundary, so callers pass the three fields flat.
*
- * PATCH-style semantics — omit a field to leave it unchanged; pass an empty
- * array to clear an allow/deny list. Backend rejects ACL writes on a
- * `PRIVATE` connection with `AclOnlyForShared` (400).
+ * PATCH-style semantics — omit a field to leave it unchanged; pass an
+ * empty array to clear an allow/deny list. Backend rejects ACL writes on
+ * a PRIVATE connection with `ComposioAclOnlyForSharedError` (400).
*
* Each field is optional, but at least one must be provided — passing an
* empty object is rejected as a no-op.
*/
-export const UpdateConnectedAccountAclParamsSchema = ConnectedAccountAclSchema.refine(
+export const UpdateConnectedAccountAclParamsSchema = ConnectedAccountAclConfigSchema.refine(
acl =>
acl.allowAllUsers !== undefined ||
acl.allowedUserIds !== undefined ||
diff --git a/ts/packages/core/src/utils/transformers/connectedAccounts.ts b/ts/packages/core/src/utils/transformers/connectedAccounts.ts
index c6f21dd68..c831535ca 100644
--- a/ts/packages/core/src/utils/transformers/connectedAccounts.ts
+++ b/ts/packages/core/src/utils/transformers/connectedAccounts.ts
@@ -18,13 +18,15 @@ type RawConnectedAccountResponseWithLabels = (
) & {
word_id?: string | null;
alias?: string | null;
- // account_type / ACL fields are added by Hermes #9860, #9882, #9902.
- // Cast lives here until @composio/client regenerates against a backend
- // spec that contains them.
+ // 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';
- allow_all_users?: boolean;
- allowed_user_ids?: string[];
- not_allowed_user_ids?: string[];
+ acl_config_for_shared?: {
+ allow_all_users: boolean;
+ allowed_user_ids: string[];
+ not_allowed_user_ids: string[];
+ };
};
/**
@@ -78,13 +80,18 @@ export function transformConnectedAccountResponse(
updatedAt: response.updated_at,
testRequestEndpoint: response.test_request_endpoint,
accountType: responseWithLabels.account_type,
- // ACL fields are conditionally visible — backend strips them 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 empty".
- allowAllUsers: responseWithLabels.allow_all_users,
- allowedUserIds: responseWithLabels.allowed_user_ids,
- notAllowedUserIds: responseWithLabels.not_allowed_user_ids,
+ // `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".
+ aclConfigForShared: responseWithLabels.acl_config_for_shared
+ ? {
+ allowAllUsers: responseWithLabels.acl_config_for_shared.allow_all_users,
+ allowedUserIds: responseWithLabels.acl_config_for_shared.allowed_user_ids,
+ notAllowedUserIds: responseWithLabels.acl_config_for_shared.not_allowed_user_ids,
+ }
+ : undefined,
}));
}