Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 22, 00:45 UTC
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';