Managing multiple accounts

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.

Default account behavior

When multiple accounts are connected for the same toolkit:

• Each session can only use one account per toolkit at a time
• Tool Router uses the most recently connected account by default
• You can override this by explicitly selecting an account
• Each account maintains its own authentication and permissions

Connecting multiple accounts

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.

1
session = composio.create(user_id="user_123")
2
3
# Connect first account (work)
4
work_auth = session.authorize("gmail")
5
print(f"Connect work Gmail: {work_auth.redirect_url}")
6
work_connection = work_auth.wait_for_connection()
7
print(f"Work account connected: {work_connection.id}")
8
9
# Connect second account (personal)
10
personal_auth = session.authorize("gmail")
11
print(f"Connect personal Gmail: {personal_auth.redirect_url}")
12
personal_connection = personal_auth.wait_for_connection()
13
print(f"Personal account connected: {personal_connection.id}")

Selecting a specific account for a session

Each Tool Router 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:

1
# This session will use a specific Gmail account
2
session = composio.create(
3
    user_id="user_123",
4
    connected_accounts={
5
        "gmail": "ca_specific_account_id",  # Connected account ID
6
    },
7
)
8
9
# To switch accounts, create a new session with a different account ID
10
session2 = composio.create(
11
    user_id="user_123",
12
    connected_accounts={
13
        "gmail": "ca_different_account_id",  # Different account
14
    },
15
)

Listing all user accounts

To list all accounts a user has connected (not just the active one), see List accounts.

Viewing session’s active account

Use session.toolkits() to see which account is currently active in the session:

1
toolkits = session.toolkits()
2
3
for toolkit in toolkits.items:
4
    if toolkit.connection.connected_account:
5
        print(f"{toolkit.name}: {toolkit.connection.connected_account.id}")