Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
manual auth fixes
Sushmithamallesh committed
Dec 14, 2025 at 17:26 UTC
20d1f7b02811d270c20fa80857c8ed1a826b296e
1 file changed
+68
-16
fern/pages/src/tool-router/managing-multiple-accounts.mdx
+68
-16
@@ -1,52 +1,104 @@
1
---
2
-title: Managing multiple accounts for a user
2
+title: Managing multiple accounts
3
image: "https://og.composio.dev/api/og?title=Managing%20Multiple%20Accounts"
4
description: "Handle users with multiple accounts for the same toolkit"
5
keywords: "tool router, multiple accounts, connected accounts, account selection"
6
---
7
8
-Users can connect multiple accounts for the same toolkit (e.g., personal and work Gmail). Tool Router uses the most recently connected account by default.
8
+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.
9
10
-## Selecting a specific account
10
+## Default account behavior
11
12
-To use a specific account, pass it in the session config:
12
+When multiple accounts are connected for the same toolkit:
13
+- Tool Router uses 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
16
+
17
+## Connecting multiple accounts
18
+
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).
20
+
21
+<CodeGroup>
22
+```python
23
+session = composio.create(user_id="user_123")
24
+
25
+# Connect first account (work)
26
+work_auth = session.authorize("gmail")
27
+print(f"Connect work Gmail: {work_auth.redirect_url}")
28
+work_connection = work_auth.wait_for_connection()
29
+print(f"Work account connected: {work_connection.id}")
30
+
31
+# Connect second account (personal)
32
+personal_auth = session.authorize("gmail")
33
+print(f"Connect personal Gmail: {personal_auth.redirect_url}")
34
+personal_connection = personal_auth.wait_for_connection()
35
+print(f"Personal account connected: {personal_connection.id}")
36
+```
37
+```typescript
38
+const session = await composio.create("user_123");
39
+
40
+// Connect first account (work)
41
+const workAuth = await session.authorize("gmail");
42
+console.log(`Connect work Gmail: ${workAuth.redirectUrl}`);
43
+const workConnection = await workAuth.waitForConnection();
44
+console.log(`Work account connected: ${workConnection.id}`);
45
+
46
+// Connect second account (personal)
47
+const personalAuth = await session.authorize("gmail");
48
+console.log(`Connect personal Gmail: ${personalAuth.redirectUrl}`);
49
+const personalConnection = await personalAuth.waitForConnection();
50
+console.log(`Personal account connected: ${personalConnection.id}`);
51
+```
52
+</CodeGroup>
53
+
54
+<Note>
55
+Store the account IDs returned after connection to explicitly select accounts later.
56
+</Note>
57
+
58
+## Selecting a specific account for a session
59
+
60
+To use a specific account in a session, pass it in the session config:
61
62
<CodeGroup>
63
```python
64
session = composio.create(
17
- user_id=user_id,
65
+ user_id="user_123",
66
connected_accounts={
19
- "gmail": "ca_specific_account_id",
67
+ "gmail": "ca_specific_account_id", # Connected account ID
68
},
69
)
70
```
71
```typescript
24
-const session = await composio.create(userId, {
72
+const session = await composio.create("user_123", {
73
connectedAccounts: {
26
- gmail: "ca_specific_account_id",
74
+ gmail: "ca_specific_account_id", // Connected account ID
75
},
76
});
77
```
78
</CodeGroup>
79
32
-## Listing connected accounts
80
+## Listing all user accounts
81
+
82
+To list all accounts a user has connected (not just the active one), see [List accounts](/docs/connected-accounts#list-accounts) in the Connected Accounts guide.
83
+
84
+## Viewing session's active account
85
34
-Use `session.toolkits()` to see all connected accounts for a user:
86
+Use `session.toolkits()` to see which account is currently active in the session:
87
88
<CodeGroup>
89
```python
90
toolkits = session.toolkits()
91
40
-for toolkit in toolkits:
41
- if toolkit.connected_account:
42
- print(f"{toolkit.name}: {toolkit.connected_account.id}")
92
+for toolkit in toolkits.items:
93
+ if toolkit.connection.connected_account:
94
+ print(f"{toolkit.name}: {toolkit.connection.connected_account.id}")
95
```
96
```typescript
97
const toolkits = await session.toolkits();
98
47
-for (const toolkit of toolkits) {
48
- if (toolkit.connectedAccount) {
49
- console.log(`${toolkit.name}: ${toolkit.connectedAccount.id}`);
99
+for (const toolkit of toolkits.items) {
100
+ if (toolkit.connection.connectedAccount) {
101
+ console.log(`${toolkit.name}: ${toolkit.connection.connectedAccount.id}`);
102
}
103
}
104
```