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.

feat(connected-accounts): surface accountType + per-user ACL on SHARED connections

venkat8284a3a074b313
diff --git a/.changeset/connected-accounts-acl.md b/.changeset/connected-accounts-acl.md
new file mode 100644
index 000000000..044eb0e74
--- /dev/null
+++ b/.changeset/connected-accounts-acl.md
@@ -0,0 +1,29 @@
+---
+'@composio/core': minor
+---
+
+Add `accountType` and per-user ACL support for SHARED connected accounts (Hermes #9860, #9882, #9902).
+
+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).
+
+ACL resolution rule (deny wins):
+
+1. requesting `userId` ∈ `notAllowedUserIds` → DENY
+2. `allowAllUsers === true` → ALLOW
+3. requesting `userId` ∈ `allowedUserIds` → ALLOW
+4. otherwise → DENY (deny-by-default)
+
+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.
+
+Python SDK gets the matching change in the same release train.
diff --git a/ts/packages/core/src/errors/ConnectedAccountsErrors.ts b/ts/packages/core/src/errors/ConnectedAccountsErrors.ts
index aaac03634..b18786db8 100644
--- a/ts/packages/core/src/errors/ConnectedAccountsErrors.ts
+++ b/ts/packages/core/src/errors/ConnectedAccountsErrors.ts
@@ -5,6 +5,9 @@ export const ConnectedAccountErrorCodes = {
MULTIPLE_CONNECTED_ACCOUNTS: 'MULTIPLE_CONNECTED_ACCOUNTS',
FAILED_TO_CREATE_CONNECTED_ACCOUNT_LINK: 'FAILED_TO_CREATE_CONNECTED_ACCOUNT_LINK',
LEGACY_CONNECTED_ACCOUNTS_ENDPOINT_RETIRED: 'LEGACY_CONNECTED_ACCOUNTS_ENDPOINT_RETIRED',
+ SHARED_ACCESS_DENIED: 'SHARED_ACCESS_DENIED',
+ ACL_ONLY_FOR_SHARED: 'ACL_ONLY_FOR_SHARED',
+ SHARED_CONNECTION_NOT_ACCESSIBLE: 'SHARED_CONNECTION_NOT_ACCESSIBLE',
} as const;
export class ComposioConnectedAccountNotFoundError extends ComposioError {
@@ -66,6 +69,83 @@ export class ComposioFailedToCreateConnectedAccountLink extends ComposioError {
*
* See: https://docs.composio.dev/docs/changelog/2026/04/24
*/
+/**
+ * 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`.
+ */
+export class ComposioSharedAccessDeniedError extends ComposioError {
+ constructor(
+ message: string = 'Access denied: this SHARED connected account is not available to the requesting user',
+ options: Omit<ComposioErrorOptions, 'code' | 'statusCode'> = {}
+ ) {
+ super(message, {
+ ...options,
+ code: ConnectedAccountErrorCodes.SHARED_ACCESS_DENIED,
+ statusCode: 403,
+ possibleFixes: options.possibleFixes || [
+ "Ask the connection's creator to grant access via composio.connectedAccounts.updateAcl() — set allowAllUsers, add the userId to allowedUserIds, or remove it from notAllowedUserIds.",
+ ],
+ });
+ this.name = 'ComposioSharedAccessDeniedError';
+ }
+}
+
+/**
+ * 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`.
+ */
+export class ComposioAclOnlyForSharedError extends ComposioError {
+ constructor(
+ message: string = 'ACL fields are only valid on SHARED connected accounts',
+ options: Omit<ComposioErrorOptions, 'code' | 'statusCode'> = {}
+ ) {
+ super(message, {
+ ...options,
+ code: ConnectedAccountErrorCodes.ACL_ONLY_FOR_SHARED,
+ statusCode: 400,
+ possibleFixes: options.possibleFixes || [
+ 'Set accountType: "SHARED" at create time, or omit ACL fields when creating/updating a PRIVATE connection.',
+ ],
+ });
+ this.name = 'ComposioAclOnlyForSharedError';
+ }
+}
+
+/**
+ * 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`.
+ */
+export class ComposioSharedConnectionNotAccessibleError extends ComposioError {
+ constructor(
+ message: string = 'A SHARED connected account pinned in the session config is not accessible to the session user',
+ options: Omit<ComposioErrorOptions, 'code' | 'statusCode'> = {}
+ ) {
+ super(message, {
+ ...options,
+ code: ConnectedAccountErrorCodes.SHARED_CONNECTION_NOT_ACCESSIBLE,
+ statusCode: 400,
+ possibleFixes: options.possibleFixes || [
+ "Grant the session user access via composio.connectedAccounts.updateAcl() on the pinned connection, or pin a different connection the user can use.",
+ ],
+ });
+ this.name = 'ComposioSharedConnectionNotAccessibleError';
+ }
+}
+
export class ComposioLegacyConnectedAccountsEndpointRetiredError extends ComposioError {
constructor(
message: string = 'POST /api/v3/connected_accounts is no longer supported for Composio-managed OAuth auth configs. Use composio.connectedAccounts.link() instead.',
diff --git a/ts/packages/core/src/models/ConnectedAccounts.ts b/ts/packages/core/src/models/ConnectedAccounts.ts
index d47b539c9..93c79ae10 100644
--- a/ts/packages/core/src/models/ConnectedAccounts.ts
+++ b/ts/packages/core/src/models/ConnectedAccounts.ts
@@ -29,6 +29,8 @@ import {
ConnectedAccountRefreshOptionsSchema,
UpdateConnectedAccountParams,
UpdateConnectedAccountParamsSchema,
+ UpdateConnectedAccountAclParams,
+ UpdateConnectedAccountAclParamsSchema,
} from '../types/connectedAccounts.types';
import { ConnectionRequest } from '../types/connectionRequest.types';
import { createConnectionRequest } from './ConnectionRequest';
@@ -50,6 +52,33 @@ 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.
+type LinkCreateBodyWithAcl = ConnectedAccountCreateParamsRaw extends never
+ ? never
+ : Record<string, unknown> & {
+ auth_config_id: string;
+ user_id: string;
+ alias?: string;
+ callback_url?: string;
+ account_type?: 'PRIVATE' | 'SHARED';
+ allow_all_users?: boolean;
+ allowed_user_ids?: string[];
+ not_allowed_user_ids?: string[];
+ };
+
+// Wire-level body for PATCH /connected_accounts/{id} with ACL fields
+// (Hermes #9902). Mirrors the same forward-compat pattern as
+// `LinkCreateBodyWithAcl` above.
+type ConnectedAccountPatchBodyWithAcl = {
+ alias?: string;
+ allow_all_users?: boolean;
+ allowed_user_ids?: string[];
+ not_allowed_user_ids?: string[];
+};
+
/**
* ConnectedAccounts class
*
@@ -366,13 +395,26 @@ export class ConnectedAccounts {
);
}
+ const opts = requestOptions.data;
+ 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,
+ }),
+ };
+
try {
- const response = await this.client.link.create({
- auth_config_id: authConfigId,
- user_id: userId,
- ...(requestOptions?.data.callbackUrl && { callback_url: requestOptions.data.callbackUrl }),
- ...(requestOptions?.data.alias != null && { alias: requestOptions.data.alias }),
- });
+ // Cast retained until @composio/client adds account_type / ACL fields
+ // to LinkCreateParams.
+ const response = await this.client.link.create(body as unknown as Parameters<
+ typeof this.client.link.create
+ >[0]);
const connectionRequest = createConnectionRequest(
this.client,
@@ -594,4 +636,69 @@ export class ConnectedAccounts {
return this.client.connectedAccounts.updateStatus(nanoid, parsedParams.data);
}
+
+ /**
+ * 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).
+ *
+ * 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
+ *
+ * @example
+ * ```typescript
+ * // Open access to everyone in the project
+ * await composio.connectedAccounts.updateAcl('ca_abc', { allowAllUsers: true });
+ *
+ * // Everyone except a specific user
+ * await composio.connectedAccounts.updateAcl('ca_abc', {
+ * allowAllUsers: true,
+ * notAllowedUserIds: ['user_bob'],
+ * });
+ *
+ * // Targeted allow
+ * await composio.connectedAccounts.updateAcl('ca_abc', {
+ * allowedUserIds: ['user_alice', 'user_bob'],
+ * });
+ *
+ * // Revoke a previously-granted allow list (back to deny-by-default)
+ * await composio.connectedAccounts.updateAcl('ca_abc', { allowedUserIds: [] });
+ * ```
+ */
+ async updateAcl(nanoid: string, params: UpdateConnectedAccountAclParams): Promise<void> {
+ const parsedParams = UpdateConnectedAccountAclParamsSchema.safeParse(params);
+ if (!parsedParams.success) {
+ throw new ValidationError('Failed to parse connected account ACL update params', {
+ cause: parsedParams.error,
+ });
+ }
+
+ 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,
+ }),
+ };
+
+ // Cast retained until @composio/client adds ACL fields to
+ // ConnectedAccountPatchParams.
+ await this.client.connectedAccounts.patch(
+ nanoid,
+ body as unknown as Parameters<typeof this.client.connectedAccounts.patch>[1]
+ );
+ }
}
diff --git a/ts/packages/core/src/types/connectedAccounts.types.ts b/ts/packages/core/src/types/connectedAccounts.types.ts
index 2135c28a5..9f9157fca 100644
--- a/ts/packages/core/src/types/connectedAccounts.types.ts
+++ b/ts/packages/core/src/types/connectedAccounts.types.ts
@@ -27,6 +27,60 @@ export type ConnectedAccountStatus =
(typeof ConnectedAccountStatuses)[keyof typeof ConnectedAccountStatuses];
export type ConnectedAccountStatusEnum = z.infer<typeof ConnectedAccountStatusSchema>;
+/**
+ * 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.
+ */
+export const ConnectedAccountTypes = {
+ PRIVATE: 'PRIVATE',
+ SHARED: 'SHARED',
+} as const;
+export const ConnectedAccountTypeSchema = z.enum([
+ ConnectedAccountTypes.PRIVATE,
+ ConnectedAccountTypes.SHARED,
+]);
+export type ConnectedAccountType =
+ (typeof ConnectedAccountTypes)[keyof typeof ConnectedAccountTypes];
+
+/**
+ * Per-user access control for a SHARED connected account. Inert for PRIVATE.
+ *
+ * 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.
+ *
+ * Lists are capped at 1000 entries each by the backend.
+ */
+const ACL_LIST_LIMIT = 1000;
+export const ConnectedAccountAclSchema = 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)
+ .optional()
+ .describe('Explicit allow list (developer-assigned user_id strings). Default [].'),
+ notAllowedUserIds: z
+ .array(z.string())
+ .max(ACL_LIST_LIMIT)
+ .optional()
+ .describe('Explicit deny list. Wins over allow on conflict. Default [].'),
+});
+export type ConnectedAccountAcl = z.infer<typeof ConnectedAccountAclSchema>;
+
export const CreateConnectedAccountParamsSchema = z.object({
authConfig: z.object({
id: z.string(),
@@ -108,6 +162,10 @@ export const ConnectedAccountRetrieveResponseSchema: z.ZodType<{
isDisabled: boolean;
createdAt: string;
updatedAt: string;
+ accountType?: ConnectedAccountType;
+ allowAllUsers?: boolean;
+ allowedUserIds?: string[];
+ notAllowedUserIds?: string[];
}> = z.object({
id: z.string(),
authConfig: ConnectedAccountAuthConfigSchema,
@@ -131,6 +189,13 @@ export const ConnectedAccountRetrieveResponseSchema: z.ZodType<{
isDisabled: z.boolean(),
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(),
});
export type ConnectedAccountRetrieveResponse = z.infer<
@@ -205,6 +270,25 @@ export const CreateConnectedAccountLinkOptionsSchema = z.object({
* `multiAccount` config to disambiguate at execution time.
*/
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.
+ */
+ accountType: ConnectedAccountTypeSchema.optional(),
+ /**
+ * ACL for SHARED connections. Ignored when `accountType !== 'SHARED'`; the
+ * backend rejects ACL fields on a `PRIVATE` connection with `AclOnlyForShared`.
+ *
+ * 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.
+ */
+ allowAllUsers: ConnectedAccountAclSchema.shape.allowAllUsers,
+ allowedUserIds: ConnectedAccountAclSchema.shape.allowedUserIds,
+ notAllowedUserIds: ConnectedAccountAclSchema.shape.notAllowedUserIds,
});
export type CreateConnectedAccountLinkOptions = z.infer<
typeof CreateConnectedAccountLinkOptionsSchema
@@ -229,3 +313,25 @@ export type { ConnectedAccountUpdateStatusParams as UpdateConnectedAccountParams
export const UpdateConnectedAccountParamsSchema = z.object({
enabled: z.boolean(),
});
+
+/**
+ * Params for `composio.connectedAccounts.updateAcl()`.
+ *
+ * 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).
+ *
+ * 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(
+ acl =>
+ acl.allowAllUsers !== undefined ||
+ acl.allowedUserIds !== undefined ||
+ acl.notAllowedUserIds !== undefined,
+ {
+ message:
+ 'At least one of allowAllUsers, allowedUserIds, or notAllowedUserIds must be provided',
+ }
+);
+export type UpdateConnectedAccountAclParams = z.infer<typeof UpdateConnectedAccountAclParamsSchema>;
diff --git a/ts/packages/core/src/utils/transformers/connectedAccounts.ts b/ts/packages/core/src/utils/transformers/connectedAccounts.ts
index 0dc34a378..c6f21dd68 100644
--- a/ts/packages/core/src/utils/transformers/connectedAccounts.ts
+++ b/ts/packages/core/src/utils/transformers/connectedAccounts.ts
@@ -18,6 +18,13 @@ 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?: 'PRIVATE' | 'SHARED';
+ allow_all_users?: boolean;
+ allowed_user_ids?: string[];
+ not_allowed_user_ids?: string[];
};
/**
@@ -70,6 +77,14 @@ export function transformConnectedAccountResponse(
createdAt: response.created_at,
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,
}));
}