Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: add multi-account mode and connection aliases documentation
Update the managing-multiple-connected-accounts guide with: - Multi-account session config (enable, maxAccountsPerToolkit, requireExplicitSelection) - Connection aliases (set during authorize/initiate/link, update/clear after) - Configuration options table with defaults Add changelog entry for both features. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Abir Taheer committed
Apr 9, 2026 at 21:02 UTC
7036768b9ae5c3d80bd8486f73c43391eb938004
2 files changed
+184
-56
docs/content/changelog/04-09-26-multi-account-aliases.mdx
new
+39
@@ -0,0 +1,39 @@
1
+---
2
+title: "Multi-Account Mode & Connection Aliases"
3
+description: "Enable multiple connected accounts per toolkit and label them with human-readable aliases"
4
+date: "2026-04-09"
5
+---
6
+
7
+Two features for managing multiple accounts per toolkit.
8
+
9
+## Multi-account mode
10
+
11
+Sessions now support a `multiAccount` config that lets users connect and use multiple accounts for the same toolkit (e.g., work and personal Gmail) within a single session.
12
+
13
+```typescript
14
+const session = await composio.create('user_123', {
15
+ toolkits: ['gmail'],
16
+ multiAccount: {
17
+ enable: true,
18
+ maxAccountsPerToolkit: 3,
19
+ },
20
+});
21
+```
22
+
23
+By default, multi-account mode is disabled and each session uses one account per toolkit.
24
+
25
+## Connection aliases
26
+
27
+Connected accounts can now have human-readable aliases (e.g., `"work-gmail"`, `"personal-github"`). Aliases can be set during connection or updated after.
28
+
29
+```typescript
30
+// Set alias during connection
31
+await session.authorize('gmail', { alias: 'work-gmail' });
32
+
33
+// Update alias on an existing account
34
+await composio.connectedAccounts.update('ca_abc123', { alias: 'work-gmail' });
35
+```
36
+
37
+Aliases must be unique per user and toolkit within a project.
38
+
39
+See the [multi-account guide](/docs/managing-multiple-connected-accounts) for full details.
docs/content/docs/managing-multiple-connected-accounts.mdx
+145
-56
@@ -1,87 +1,187 @@
1
---
2
title: Managing multiple connected accounts
3
-description: Handle users with multiple accounts for the same toolkit
4
-keywords: [multiple accounts, work personal, switch account]
3
+description: Handle users with multiple accounts for the same toolkit using multi-account mode and aliases
4
+keywords: [multiple accounts, multi-account, work personal, switch account, alias, account selection]
5
---
6
7
-Users can connect multiple accounts for the same toolkit (e.g., personal and work Gmail accounts). This is useful when users need to manage different email accounts, GitHub organizations, or separate work and personal contexts. This guide explains how to connect, select, and manage multiple accounts. For background on how users, sessions, and connected accounts relate, see [Users & Sessions](/docs/users-and-sessions).
7
+Users can connect multiple accounts for the same toolkit (e.g., personal and work Gmail accounts). This guide covers how to enable multi-account mode, label accounts with aliases, and select which account to use.
8
9
-## Default account behavior
9
+## Multi-account mode
10
11
-When multiple accounts are connected for the same toolkit:
12
-- Each session can only use **one account per toolkit** at a time
13
-- Sessions use the **most recently connected account** by default
14
-- You can override this by explicitly selecting an account
15
-- Each account maintains its own authentication and permissions
11
+By default, each session uses **one account per toolkit**. Enable multi-account mode to let users connect and use multiple accounts for the same toolkit within a single session.
12
+
13
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
14
+<Tab value="Python">
15
+```python
16
+session = composio.create(
17
+ user_id="user_123",
18
+ toolkits=["gmail"],
19
+ multi_account={
20
+ "enable": True,
21
+ "max_accounts_per_toolkit": 3,
22
+ },
23
+)
24
+```
25
+</Tab>
26
+<Tab value="TypeScript">
27
+```typescript
28
+import { Composio } from '@composio/core';
29
+const composio = new Composio({ apiKey: 'your_api_key' });
30
+// ---cut---
31
+const session = await composio.create("user_123", {
32
+ toolkits: ["gmail"],
33
+ multiAccount: {
34
+ enable: true,
35
+ maxAccountsPerToolkit: 3,
36
+ },
37
+});
38
+```
39
+</Tab>
40
+</Tabs>
41
+
42
+### Configuration options
43
+
44
+| Option | Type | Default | Description |
45
+|--------|------|---------|-------------|
46
+| `enable` | `boolean` | `false` | Enable multi-account mode for this session |
47
+| `maxAccountsPerToolkit` | `number` | `5` | Maximum connected accounts per toolkit (2-10) |
48
+| `requireExplicitSelection` | `boolean` | `false` | When true, the agent must specify which account to use instead of defaulting to the most recent |
49
+
50
+When multi-account mode is disabled (the default), each session uses the most recently connected account for each toolkit.
51
52
## Connecting multiple accounts
53
19
-Call `session.authorize()` multiple times for the same toolkit. Each authorization creates a separate connected account with its own ID. The most recently connected account becomes the active one for that session. New sessions will also use the most recent account unless you [explicitly select a different one](#selecting-a-specific-account-for-a-session).
54
+Call `session.authorize()` multiple times for the same toolkit. Each call creates a separate connected account.
55
56
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
57
<Tab value="Python">
58
```python
24
-session = composio.create(user_id="user_123")
25
-
26
-# Connect first account (work)
27
-work_auth = session.authorize("gmail")
59
+# Connect work account
60
+work_auth = session.authorize("gmail", alias="work-gmail")
61
print(f"Connect work Gmail: {work_auth.redirect_url}")
62
work_connection = work_auth.wait_for_connection()
30
-print(f"Work account connected: {work_connection.id}")
63
32
-# Connect second account (personal)
33
-personal_auth = session.authorize("gmail")
64
+# Connect personal account
65
+personal_auth = session.authorize("gmail", alias="personal-gmail")
66
print(f"Connect personal Gmail: {personal_auth.redirect_url}")
67
personal_connection = personal_auth.wait_for_connection()
36
-print(f"Personal account connected: {personal_connection.id}")
68
```
69
</Tab>
70
<Tab value="TypeScript">
71
```typescript
72
import { Composio } from '@composio/core';
73
const composio = new Composio({ apiKey: 'your_api_key' });
43
-// ---cut---
74
const session = await composio.create("user_123");
45
-
46
-// Connect first account (work)
47
-const workAuth = await session.authorize("gmail");
75
+// ---cut---
76
+// Connect work account
77
+const workAuth = await session.authorize("gmail", { alias: "work-gmail" });
78
console.log(`Connect work Gmail: ${workAuth.redirectUrl}`);
79
const workConnection = await workAuth.waitForConnection();
50
-console.log(`Work account connected: ${workConnection.id}`);
80
52
-// Connect second account (personal)
53
-const personalAuth = await session.authorize("gmail");
81
+// Connect personal account
82
+const personalAuth = await session.authorize("gmail", { alias: "personal-gmail" });
83
console.log(`Connect personal Gmail: ${personalAuth.redirectUrl}`);
84
const personalConnection = await personalAuth.waitForConnection();
56
-console.log(`Personal account connected: ${personalConnection.id}`);
85
```
86
</Tab>
87
</Tabs>
88
61
-<Callout type="info">
62
-Store the account IDs returned after connection to explicitly select accounts later.
63
-</Callout>
89
+## Aliases
90
65
-## Selecting a specific account for a session
91
+Aliases are human-readable labels for connected accounts (e.g., `"work-gmail"`, `"personal-github"`). They make it easier for agents and users to identify which account is which.
92
+
93
+- Must be unique per user and toolkit within a project
94
+- Can be set during connection or updated after
95
67
-Each session can only use one account per toolkit at a time. To use a specific account in a session, pass it in the session config:
96
+### Setting an alias during connection
97
+
98
+Pass `alias` to `session.authorize()`, `connectedAccounts.initiate()`, or `connectedAccounts.link()`:
99
100
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
101
<Tab value="Python">
102
```python
72
-# This session will use a specific Gmail account
73
-session = composio.create(
74
- user_id="user_123",
75
- connected_accounts={
76
- "gmail": "ca_specific_account_id", # Connected account ID
77
- },
103
+# Via session.authorize()
104
+connection_request = session.authorize("gmail", alias="work-gmail")
105
+
106
+# Via connectedAccounts.initiate()
107
+connection_request = composio.connected_accounts.initiate(
108
+ "user_123",
109
+ "ac_auth_config_id",
110
+ alias="work-gmail",
111
)
112
80
-# To switch accounts, create a new session with a different account ID
81
-session2 = composio.create(
113
+# Via connectedAccounts.link()
114
+connection_request = composio.connected_accounts.link(
115
+ "user_123",
116
+ "ac_auth_config_id",
117
+ alias="work-gmail",
118
+)
119
+```
120
+</Tab>
121
+<Tab value="TypeScript">
122
+```typescript
123
+import { Composio } from '@composio/core';
124
+const composio = new Composio({ apiKey: 'your_api_key' });
125
+const session = await composio.create("user_123");
126
+// ---cut---
127
+// Via session.authorize()
128
+const connectionRequest = await session.authorize("gmail", { alias: "work-gmail" });
129
+
130
+// Via connectedAccounts.initiate()
131
+const connectionRequest2 = await composio.connectedAccounts.initiate(
132
+ "user_123",
133
+ "ac_auth_config_id",
134
+ { alias: "work-gmail" },
135
+);
136
+
137
+// Via connectedAccounts.link()
138
+const connectionRequest3 = await composio.connectedAccounts.link(
139
+ "user_123",
140
+ "ac_auth_config_id",
141
+ { alias: "work-gmail" },
142
+);
143
+```
144
+</Tab>
145
+</Tabs>
146
+
147
+### Updating or clearing an alias
148
+
149
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
150
+<Tab value="Python">
151
+```python
152
+# Set or update an alias
153
+composio.connected_accounts.update("ca_abc123", alias="work-gmail")
154
+
155
+# Clear an alias
156
+composio.connected_accounts.update("ca_abc123", alias="")
157
+```
158
+</Tab>
159
+<Tab value="TypeScript">
160
+```typescript
161
+import { Composio } from '@composio/core';
162
+const composio = new Composio({ apiKey: 'your_api_key' });
163
+// ---cut---
164
+// Set or update an alias
165
+await composio.connectedAccounts.update("ca_abc123", { alias: "work-gmail" });
166
+
167
+// Clear an alias
168
+await composio.connectedAccounts.update("ca_abc123", { alias: "" });
169
+```
170
+</Tab>
171
+</Tabs>
172
+
173
+## Selecting a specific account for a session
174
+
175
+Pin a session to specific accounts by passing their IDs in the session config:
176
+
177
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
178
+<Tab value="Python">
179
+```python
180
+session = composio.create(
181
user_id="user_123",
182
connected_accounts={
84
- "gmail": "ca_different_account_id", # Different account
183
+ "gmail": "ca_work_gmail_id",
184
+ "github": "ca_personal_github_id",
185
},
186
)
187
```
@@ -91,30 +191,19 @@ session2 = composio.create(
191
import { Composio } from '@composio/core';
192
const composio = new Composio({ apiKey: 'your_api_key' });
193
// ---cut---
94
-// This session will use a specific Gmail account
194
const session = await composio.create("user_123", {
195
connectedAccounts: {
97
- gmail: "ca_specific_account_id", // Connected account ID
98
- },
99
-});
100
-
101
-// To switch accounts, create a new session with a different account ID
102
-const session2 = await composio.create("user_123", {
103
- connectedAccounts: {
104
- gmail: "ca_different_account_id", // Different account
196
+ gmail: "ca_work_gmail_id",
197
+ github: "ca_personal_github_id",
198
},
199
});
200
```
201
</Tab>
202
</Tabs>
203
111
-## Listing all user accounts
112
-
113
-To list all accounts a user has connected (not just the active one), see [List accounts](/docs/auth-configuration/connected-accounts#list-accounts).
114
-
115
-## Viewing session's active account
204
+## Viewing session's active accounts
205
117
-Use `session.toolkits()` to see which account is currently active in the session:
206
+Use `session.toolkits()` to see which accounts are currently active:
207
208
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
209
<Tab value="Python">
@@ -122,7 +211,7 @@ Use `session.toolkits()` to see which account is currently active in the session
211
toolkits = session.toolkits()
212
213
for toolkit in toolkits.items:
125
- if toolkit.connection.connected_account:
214
+ if toolkit.connection and toolkit.connection.connected_account:
215
print(f"{toolkit.name}: {toolkit.connection.connected_account.id}")
216
```
217
</Tab>