Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.mdnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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 UpdateConnectedAccountParamsexport 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.tsindex 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,}));}