Skip to main content
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

For a runnable agent with work and personal Gmail accounts, follow the multiple accounts walkthrough. 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.

Configuration options

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.

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
To identify an account by its provider-side identity (e.g. the Gmail address or GitHub username) rather than a label you set, read the read-only displayName that Composio auto-populates on the connected account at state.val.displayName once the connection is active. See Identify the connected account to display that identity or retrieve the provider’s profile. To accept only certain email domains, follow Restrict Gmail connections to an email domain.

Setting an alias during connection

Pass alias to session.authorize():
The direct-execution methods connectedAccounts.initiate() and connectedAccounts.link() accept the same alias parameter. To create another active connection for the same user and auth config, also pass allow_multiple=True in Python or allowMultiple: true in TypeScript.

Updating or clearing an 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.

Viewing session’s active accounts

Use session.toolkits() to see which accounts are currently active:

Next

Shared connections