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: add alias support to connected account creation flow

Zen Agentb4785d072718
diff --git a/docs/content/docs/configuring-sessions.mdx b/docs/content/docs/configuring-sessions.mdx
index 0513291c8..ad8f892ee 100644
--- a/docs/content/docs/configuring-sessions.mdx
+++ b/docs/content/docs/configuring-sessions.mdx
@@ -236,6 +236,35 @@ await composio.connectedAccounts.update("ca_abc123", { alias: "" });
Aliases must be unique per entity and toolkit within a project.
+You can also set an alias at creation time when initiating a new connection:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+<Tab value="Python">
+```python
+# Set alias when creating a connected account
+connection = composio.connected_accounts.initiate(
+ "user_123",
+ "auth_config_123",
+ alias="work-gmail",
+)
+```
+</Tab>
+<Tab value="TypeScript">
+```typescript
+// @errors: 2353
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your_api_key' });
+// ---cut---
+// Set alias when creating a connected account
+const connection = await composio.connectedAccounts.initiate(
+ "user_123",
+ "auth_config_123",
+ { alias: "work-gmail" },
+);
+```
+</Tab>
+</Tabs>
+
## Disabling workbench
By default, sessions include the [workbench](/docs/workbench) — a persistent sandbox that provides `COMPOSIO_REMOTE_WORKBENCH` and `COMPOSIO_REMOTE_BASH_TOOL`. If your use case doesn't need code execution, you can disable it:
diff --git a/python/composio/core/models/connected_accounts.py b/python/composio/core/models/connected_accounts.py
index e3f30acc5..010596697 100644
--- a/python/composio/core/models/connected_accounts.py
+++ b/python/composio/core/models/connected_accounts.py
@@ -397,6 +397,7 @@ class ConnectedAccounts:
callback_url: t.Optional[str] = None,
allow_multiple: bool = False,
config: t.Optional[connected_account_create_params.ConnectionState] = None,
+ alias: t.Optional[str] = None,
) -> ConnectionRequest:
"""
Compound function to create a new connected account. This function creates
@@ -410,6 +411,7 @@ class ConnectedAccounts:
:param callback_url: Callback URL to use for OAuth apps.
:param config: The configuration to create the connected account with.
:param allow_multiple: Whether to allow multiple connected accounts for the same user and auth config.
+ :param alias: Optional human-readable alias for the account. Must be unique per entity and toolkit within the project.
:return: The connection request.
"""
# Check if there are multiple connected accounts for the authConfig of the user
@@ -435,10 +437,14 @@ class ConnectedAccounts:
if config is not None:
connection["state"] = config
- response = self._client.connected_accounts.create(
- auth_config={"id": auth_config_id},
- connection=t.cast(connected_account_create_params.Connection, connection),
- )
+ create_kwargs: dict[str, t.Any] = {
+ "auth_config": {"id": auth_config_id},
+ "connection": t.cast(connected_account_create_params.Connection, connection),
+ }
+ if alias is not None:
+ create_kwargs["alias"] = alias
+
+ response = self._client.connected_accounts.create(**create_kwargs)
return ConnectionRequest(
id=response.id,
status=response.connection_data.val.status,
@@ -452,6 +458,7 @@ class ConnectedAccounts:
auth_config_id: str,
*,
callback_url: t.Optional[str] = None,
+ alias: t.Optional[str] = None,
) -> ConnectionRequest:
"""
Create a Composio Connect Link for a user to connect their account to a given auth config.
@@ -495,6 +502,10 @@ class ConnectedAccounts:
if callback_url is not None:
payload["callback_url"] = callback_url
+ # Add alias only if provided
+ if alias is not None:
+ payload["alias"] = alias
+
# Call the link creation endpoint
response = self._client.link.create(**payload)
diff --git a/ts/packages/core/src/models/ConnectedAccounts.ts b/ts/packages/core/src/models/ConnectedAccounts.ts
index e118d8538..9a8772b7e 100644
--- a/ts/packages/core/src/models/ConnectedAccounts.ts
+++ b/ts/packages/core/src/models/ConnectedAccounts.ts
@@ -202,6 +202,7 @@ export class ConnectedAccounts {
user_id: userId,
state,
},
+ ...(options?.alias && { alias: options.alias }),
// @TODO: This is a temporary fix to allow api_key to be optional, in future ideally we should fix this from API side
} as ConnectedAccountCreateParamsRaw);
@@ -270,6 +271,7 @@ export class ConnectedAccounts {
auth_config_id: authConfigId,
user_id: userId,
...(requestOptions?.data.callbackUrl && { callback_url: requestOptions.data.callbackUrl }),
+ ...(requestOptions?.data.alias && { alias: requestOptions.data.alias }),
});
const connectionRequest = createConnectionRequest(
diff --git a/ts/packages/core/src/types/connectedAccounts.types.ts b/ts/packages/core/src/types/connectedAccounts.types.ts
index 2a2c113ec..740682e76 100644
--- a/ts/packages/core/src/types/connectedAccounts.types.ts
+++ b/ts/packages/core/src/types/connectedAccounts.types.ts
@@ -43,6 +43,7 @@ export const DefaultCreateConnectedAccountParamsSchema: z.ZodType<{
callback_url?: string;
user_id?: string;
};
+ alias?: string;
}> = z.object({
auth_config: z.object({
id: z.string(),
@@ -53,16 +54,19 @@ export const DefaultCreateConnectedAccountParamsSchema: z.ZodType<{
callback_url: z.string().optional(),
user_id: z.string().optional(),
}),
+ alias: z.string().optional(),
});
export const CreateConnectedAccountOptionsSchema: z.ZodType<{
allowMultiple?: boolean;
callbackUrl?: string;
config?: z.infer<typeof ConnectionDataSchema>;
+ alias?: string;
}> = z.object({
allowMultiple: z.boolean().optional(),
callbackUrl: z.string().optional(),
config: ConnectionDataSchema.optional(),
+ alias: z.string().optional(),
});
export type CreateConnectedAccountOptions = z.infer<typeof CreateConnectedAccountOptionsSchema>;
export type CreateConnectedAccountParams = z.infer<typeof CreateConnectedAccountParamsSchema>;
@@ -187,6 +191,10 @@ export const CreateConnectedAccountLinkOptionsSchema = z.object({
*
*/
callbackUrl: z.string().optional(),
+ /**
+ * Human-readable alias for the connected account. Must be unique per entity and toolkit within the project.
+ */
+ alias: z.string().optional(),
});
export type CreateConnectedAccountLinkOptions = z.infer<
typeof CreateConnectedAccountLinkOptionsSchema
diff --git a/ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts b/ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts
index 121fee675..4e3e1b6f1 100644
--- a/ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts
+++ b/ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts
@@ -180,6 +180,71 @@ describe('ConnectedAccounts', () => {
expect(typeof connectionRequest.waitForConnection).toBe('function');
});
+ it('should pass alias to the create API when provided', async () => {
+ const userId = 'user_123';
+ const authConfigId = 'auth_config_123';
+
+ extendedMockClient.connectedAccounts.list.mockResolvedValueOnce({
+ items: [],
+ next_cursor: null,
+ total_pages: 1,
+ });
+
+ const mockResponse = {
+ id: 'conn_123',
+ connectionData: {
+ val: {
+ authScheme: AuthSchemeTypes.OAUTH2,
+ status: 'INITIALIZING',
+ redirectUrl: 'https://auth.example.com/connect',
+ },
+ },
+ };
+
+ extendedMockClient.connectedAccounts.create.mockResolvedValueOnce(mockResponse);
+
+ await connectedAccounts.initiate(userId, authConfigId, {
+ alias: 'work-gmail',
+ });
+
+ expect(extendedMockClient.connectedAccounts.create).toHaveBeenCalledWith(
+ expect.objectContaining({
+ alias: 'work-gmail',
+ auth_config: { id: authConfigId },
+ connection: expect.objectContaining({ user_id: userId }),
+ })
+ );
+ });
+
+ it('should not include alias in create params when not provided', async () => {
+ const userId = 'user_123';
+ const authConfigId = 'auth_config_123';
+
+ extendedMockClient.connectedAccounts.list.mockResolvedValueOnce({
+ items: [],
+ next_cursor: null,
+ total_pages: 1,
+ });
+
+ const mockResponse = {
+ id: 'conn_123',
+ connectionData: {
+ val: {
+ authScheme: AuthSchemeTypes.OAUTH2,
+ status: 'INITIALIZING',
+ redirectUrl: 'https://auth.example.com/connect',
+ },
+ },
+ };
+
+ extendedMockClient.connectedAccounts.create.mockResolvedValueOnce(mockResponse);
+
+ await connectedAccounts.initiate(userId, authConfigId);
+
+ const callArgs = extendedMockClient.connectedAccounts.create.mock.calls[0]![0];
+ expect(callArgs).not.toHaveProperty('alias');
+ });
+
it('should throw ComposioMultipleConnectedAccountsError when multiple accounts exist and allowMultiple is false', async () => {
const userId = 'user_123';
const authConfigId = 'auth_config_123';