@devries-cameron20 / composio-1 / commits / b4785d072
Fork 0

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

Allow passing an optional alias when creating a connected account via initiate() and link() in both TypeScript and Python SDKs. This complements the existing update() method for setting aliases post-creation. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Zen Agent committed Apr 9, 2026 at 01:10 UTC b4785d07271816e37e3e5f6d72fda50550492133
5 files changed +119 -4
docs/content/docs/configuring-sessions.mdx
+29
@@ -236,6 +236,35 @@ await composio.connectedAccounts.update("ca_abc123", { alias: "" });
236
237 Aliases must be unique per entity and toolkit within a project.
238
239 +You can also set an alias at creation time when initiating a new connection:
240 +
241 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
242 +<Tab value="Python">
243 +```python
244 +# Set alias when creating a connected account
245 +connection = composio.connected_accounts.initiate(
246 + "user_123",
247 + "auth_config_123",
248 + alias="work-gmail",
249 +)
250 +```
251 +</Tab>
252 +<Tab value="TypeScript">
253 +```typescript
254 +// @errors: 2353
255 +import { Composio } from '@composio/core';
256 +const composio = new Composio({ apiKey: 'your_api_key' });
257 +// ---cut---
258 +// Set alias when creating a connected account
259 +const connection = await composio.connectedAccounts.initiate(
260 + "user_123",
261 + "auth_config_123",
262 + { alias: "work-gmail" },
263 +);
264 +```
265 +</Tab>
266 +</Tabs>
267 +
268 ## Disabling workbench
269
270 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:
python/composio/core/models/connected_accounts.py
+15 -4
@@ -397,6 +397,7 @@ class ConnectedAccounts:
397 callback_url: t.Optional[str] = None,
398 allow_multiple: bool = False,
399 config: t.Optional[connected_account_create_params.ConnectionState] = None,
400 + alias: t.Optional[str] = None,
401 ) -> ConnectionRequest:
402 """
403 Compound function to create a new connected account. This function creates
@@ -410,6 +411,7 @@ class ConnectedAccounts:
411 :param callback_url: Callback URL to use for OAuth apps.
412 :param config: The configuration to create the connected account with.
413 :param allow_multiple: Whether to allow multiple connected accounts for the same user and auth config.
414 + :param alias: Optional human-readable alias for the account. Must be unique per entity and toolkit within the project.
415 :return: The connection request.
416 """
417 # Check if there are multiple connected accounts for the authConfig of the user
@@ -435,10 +437,14 @@ class ConnectedAccounts:
437 if config is not None:
438 connection["state"] = config
439
438 - response = self._client.connected_accounts.create(
439 - auth_config={"id": auth_config_id},
440 - connection=t.cast(connected_account_create_params.Connection, connection),
441 - )
440 + create_kwargs: dict[str, t.Any] = {
441 + "auth_config": {"id": auth_config_id},
442 + "connection": t.cast(connected_account_create_params.Connection, connection),
443 + }
444 + if alias is not None:
445 + create_kwargs["alias"] = alias
446 +
447 + response = self._client.connected_accounts.create(**create_kwargs)
448 return ConnectionRequest(
449 id=response.id,
450 status=response.connection_data.val.status,
@@ -452,6 +458,7 @@ class ConnectedAccounts:
458 auth_config_id: str,
459 *,
460 callback_url: t.Optional[str] = None,
461 + alias: t.Optional[str] = None,
462 ) -> ConnectionRequest:
463 """
464 Create a Composio Connect Link for a user to connect their account to a given auth config.
@@ -495,6 +502,10 @@ class ConnectedAccounts:
502 if callback_url is not None:
503 payload["callback_url"] = callback_url
504
505 + # Add alias only if provided
506 + if alias is not None:
507 + payload["alias"] = alias
508 +
509 # Call the link creation endpoint
510 response = self._client.link.create(**payload)
511
ts/packages/core/src/models/ConnectedAccounts.ts
+2
@@ -202,6 +202,7 @@ export class ConnectedAccounts {
202 user_id: userId,
203 state,
204 },
205 + ...(options?.alias && { alias: options.alias }),
206 // @TODO: This is a temporary fix to allow api_key to be optional, in future ideally we should fix this from API side
207 } as ConnectedAccountCreateParamsRaw);
208
@@ -270,6 +271,7 @@ export class ConnectedAccounts {
271 auth_config_id: authConfigId,
272 user_id: userId,
273 ...(requestOptions?.data.callbackUrl && { callback_url: requestOptions.data.callbackUrl }),
274 + ...(requestOptions?.data.alias && { alias: requestOptions.data.alias }),
275 });
276
277 const connectionRequest = createConnectionRequest(
ts/packages/core/src/types/connectedAccounts.types.ts
+8
@@ -43,6 +43,7 @@ export const DefaultCreateConnectedAccountParamsSchema: z.ZodType<{
43 callback_url?: string;
44 user_id?: string;
45 };
46 + alias?: string;
47 }> = z.object({
48 auth_config: z.object({
49 id: z.string(),
@@ -53,16 +54,19 @@ export const DefaultCreateConnectedAccountParamsSchema: z.ZodType<{
54 callback_url: z.string().optional(),
55 user_id: z.string().optional(),
56 }),
57 + alias: z.string().optional(),
58 });
59
60 export const CreateConnectedAccountOptionsSchema: z.ZodType<{
61 allowMultiple?: boolean;
62 callbackUrl?: string;
63 config?: z.infer<typeof ConnectionDataSchema>;
64 + alias?: string;
65 }> = z.object({
66 allowMultiple: z.boolean().optional(),
67 callbackUrl: z.string().optional(),
68 config: ConnectionDataSchema.optional(),
69 + alias: z.string().optional(),
70 });
71 export type CreateConnectedAccountOptions = z.infer<typeof CreateConnectedAccountOptionsSchema>;
72 export type CreateConnectedAccountParams = z.infer<typeof CreateConnectedAccountParamsSchema>;
@@ -187,6 +191,10 @@ export const CreateConnectedAccountLinkOptionsSchema = z.object({
191 *
192 */
193 callbackUrl: z.string().optional(),
194 + /**
195 + * Human-readable alias for the connected account. Must be unique per entity and toolkit within the project.
196 + */
197 + alias: z.string().optional(),
198 });
199 export type CreateConnectedAccountLinkOptions = z.infer<
200 typeof CreateConnectedAccountLinkOptionsSchema
ts/packages/core/test/connectedAccounts/connectedAccounts.test.ts
+65
@@ -180,6 +180,71 @@ describe('ConnectedAccounts', () => {
180 expect(typeof connectionRequest.waitForConnection).toBe('function');
181 });
182
183 + it('should pass alias to the create API when provided', async () => {
184 + const userId = 'user_123';
185 + const authConfigId = 'auth_config_123';
186 +
187 + extendedMockClient.connectedAccounts.list.mockResolvedValueOnce({
188 + items: [],
189 + next_cursor: null,
190 + total_pages: 1,
191 + });
192 +
193 + const mockResponse = {
194 + id: 'conn_123',
195 + connectionData: {
196 + val: {
197 + authScheme: AuthSchemeTypes.OAUTH2,
198 + status: 'INITIALIZING',
199 + redirectUrl: 'https://auth.example.com/connect',
200 + },
201 + },
202 + };
203 +
204 + extendedMockClient.connectedAccounts.create.mockResolvedValueOnce(mockResponse);
205 +
206 + await connectedAccounts.initiate(userId, authConfigId, {
207 + alias: 'work-gmail',
208 + });
209 +
210 + expect(extendedMockClient.connectedAccounts.create).toHaveBeenCalledWith(
211 + expect.objectContaining({
212 + alias: 'work-gmail',
213 + auth_config: { id: authConfigId },
214 + connection: expect.objectContaining({ user_id: userId }),
215 + })
216 + );
217 + });
218 +
219 + it('should not include alias in create params when not provided', async () => {
220 + const userId = 'user_123';
221 + const authConfigId = 'auth_config_123';
222 +
223 + extendedMockClient.connectedAccounts.list.mockResolvedValueOnce({
224 + items: [],
225 + next_cursor: null,
226 + total_pages: 1,
227 + });
228 +
229 + const mockResponse = {
230 + id: 'conn_123',
231 + connectionData: {
232 + val: {
233 + authScheme: AuthSchemeTypes.OAUTH2,
234 + status: 'INITIALIZING',
235 + redirectUrl: 'https://auth.example.com/connect',
236 + },
237 + },
238 + };
239 +
240 + extendedMockClient.connectedAccounts.create.mockResolvedValueOnce(mockResponse);
241 +
242 + await connectedAccounts.initiate(userId, authConfigId);
243 +
244 + const callArgs = extendedMockClient.connectedAccounts.create.mock.calls[0]![0];
245 + expect(callArgs).not.toHaveProperty('alias');
246 + });
247 +
248 it('should throw ComposioMultipleConnectedAccountsError when multiple accounts exist and allowMultiple is false', async () => {
249 const userId = 'user_123';
250 const authConfigId = 'auth_config_123';