Managing multiple connected accounts
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.
Multi-account mode
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.
session = composio.create(
user_id="user_123",
toolkits=["gmail"],
multi_account={
"enable": True,
"max_accounts_per_toolkit": 3,
},
)const session = await composio.create("user_123", {
toolkits: ["gmail"],
multiAccount: {
enable: true,
maxAccountsPerToolkit: 3,
},
});Configuration options
| Option (TS / Python) | Type | Default | Description |
|---|---|---|---|
enable | boolean | false | Enable multi-account mode for this session |
maxAccountsPerToolkit / max_accounts_per_toolkit | number | 5 | Maximum connected accounts per toolkit (2-10) |
requireExplicitSelection / require_explicit_selection | boolean | false | When true, the agent must specify which account to use via connectedAccounts pinning instead of defaulting to the most recent |
When multi-account mode is disabled (the default), each session uses the most recently connected account for each toolkit.
Connecting multiple accounts
Call session.authorize() multiple times for the same toolkit. Each call creates a separate connected account.
session = composio.create(user_id="user_123", multi_account={"enable": True})
# Connect work account
work_auth = session.authorize("gmail", alias="work-gmail")
print(f"Connect work Gmail: {work_auth.redirect_url}")
work_connection = work_auth.wait_for_connection()
# Connect personal account
personal_auth = session.authorize("gmail", alias="personal-gmail")
print(f"Connect personal Gmail: {personal_auth.redirect_url}")
personal_connection = personal_auth.wait_for_connection()const session = await composio.create("user_123", {
toolkits: ["gmail"],
multiAccount: { enable: true },
});
// Connect work account
const workAuth = await session.authorize("gmail", { alias: "work-gmail" });
console.log(`Connect work Gmail: ${workAuth.redirectUrl}`);
const workConnection = await workAuth.waitForConnection();
// Connect personal account
const personalAuth = await session.authorize("gmail", { alias: "personal-gmail" });
console.log(`Connect personal Gmail: ${personalAuth.redirectUrl}`);
const personalConnection = await personalAuth.waitForConnection();Aliases
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.
- Must be unique per user and toolkit within a project
- Can be set during connection or updated after
Setting an alias during connection
Pass alias to session.authorize(), connectedAccounts.initiate(), or connectedAccounts.link():
session = composio.create(user_id="user_123")
# Via session.authorize()
connection_request = session.authorize("gmail", alias="work-gmail")
# Via connectedAccounts.initiate()
connection_request = composio.connected_accounts.initiate(
"user_123",
"ac_auth_config_id",
alias="work-gmail",
)
# Via connectedAccounts.link()
connection_request = composio.connected_accounts.link(
"user_123",
"ac_auth_config_id",
alias="work-gmail",
)// Via session.authorize()
const connectionRequest = await session.authorize("gmail", { alias: "work-gmail" });
// Via connectedAccounts.initiate()
const connectionRequest2 = await composio.connectedAccounts.initiate(
"user_123",
"ac_auth_config_id",
{ alias: "work-gmail" },
);
// Via connectedAccounts.link()
const connectionRequest3 = await composio.connectedAccounts.link(
"user_123",
"ac_auth_config_id",
{ alias: "work-gmail" },
);Updating or clearing an alias
# Set or update an alias
composio.connected_accounts.update("ca_abc123", alias="work-gmail")
# Clear an alias
composio.connected_accounts.update("ca_abc123", alias="")// Set or update an alias
await composio.connectedAccounts.update("ca_abc123", { alias: "work-gmail" });
// Clear an alias
await composio.connectedAccounts.update("ca_abc123", { alias: "" });Selecting a specific account for a session
Pin a session to specific accounts by passing their IDs in the session config. To retrieve connected account IDs, see List accounts.
session = composio.create(
user_id="user_123",
connected_accounts={
"gmail": "ca_work_gmail_id",
"github": "ca_personal_github_id",
},
)const session = await composio.create("user_123", {
connectedAccounts: {
gmail: "ca_work_gmail_id",
github: "ca_personal_github_id",
},
});Viewing session's active accounts
Use session.toolkits() to see which accounts are currently active:
toolkits = session.toolkits()
for toolkit in toolkits.items:
if toolkit.connection and toolkit.connection.connected_account:
print(f"{toolkit.name}: {toolkit.connection.connected_account.id}")const toolkits = await session.toolkits();
for (const toolkit of toolkits.items) {
if (toolkit.connection?.connectedAccount) {
console.log(`${toolkit.name}: ${toolkit.connection.connectedAccount.id}`);
}
}