> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Managing multiple connected accounts

> Handle users with multiple accounts for the same toolkit using multi-account mode and aliases

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](https://composio-preview.mintlify.site/examples/multiple-accounts.md).

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.

> [tab] Python
>
> ```python theme={null}
> session = composio.create(
>     user_id="user_123",
>     toolkits=["gmail"],
>     multi_account={
>         "enable": True,
>         "max_accounts_per_toolkit": 3,
>     },
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   toolkits: ["gmail"],
>   multiAccount: {
>     enable: true,
>     maxAccountsPerToolkit: 3,
>   },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # The SDKs default require_explicit_selection to true when multi-account mode is enabled
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "toolkits": {"enable": ["gmail"]},
>     "multi_account": {"enable": true, "max_accounts_per_toolkit": 3, "require_explicit_selection": true}
>   }'
> ```

### 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 and a toolkit has multiple active connected accounts, the agent must provide the `account` parameter in the tool execution call to select which account to use. `account` can be either a connected account ID or an alias (see the Aliases section below). When false, the default account (most recently connected active account) is used automatically |

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.

> [tab] Python
>
> ```python theme={null}
> session = composio.create(
>     user_id="user_123",
>     toolkits=["gmail"],
>     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()
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> 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();
> ```

> [tab] API
>
> ```bash theme={null}
> SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "toolkits": {"enable": ["gmail"]},
>     "multi_account": {"enable": true, "require_explicit_selection": true}
>   }' | jq -r '.session_id')
>
> # Connect work account
> curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/link \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"toolkit": "gmail", "alias": "work-gmail"}' | jq -r '.redirect_url'
>
> # Connect personal account
> curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/link \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"toolkit": "gmail", "alias": "personal-gmail"}' | jq -r '.redirect_url'
> ```

## 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](https://composio-preview.mintlify.site/docs/authentication/manually-authenticating.md#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](https://composio-preview.mintlify.site/examples/restrict-gmail-domain.md).

### Setting an alias during connection

Pass `alias` to `session.authorize()`:

> [tab] Python
>
> ```python theme={null}
> session = composio.create(user_id="user_123")
>
> connection_request = session.authorize("gmail", alias="work-gmail")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123");
> const connectionRequest = await session.authorize("gmail", { alias: "work-gmail" });
> ```

> [tab] API
>
> ```bash theme={null}
> SESSION_ID=$(curl -s -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_123"}' | jq -r '.session_id')
>
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/link \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"toolkit": "gmail", "alias": "work-gmail"}'
> ```

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

> [tab] Python
>
> ```python theme={null}
> # Set or update an alias
> composio.connected_accounts.update("ca_abc123", alias="work-gmail")
>
> # Clear an alias
> composio.connected_accounts.update("ca_abc123", alias="")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> // Set or update an alias
> await composio.connectedAccounts.update("ca_abc123", { alias: "work-gmail" });
>
> // Clear an alias
> await composio.connectedAccounts.update("ca_abc123", { alias: "" });
> ```

> [tab] API
>
> ```bash theme={null}
> # Set or update an alias
> curl -X PATCH https://backend.composio.dev/api/v3.1/connected_accounts/ca_abc123 \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"alias": "work-gmail"}'
>
> # Clear an alias
> curl -X PATCH https://backend.composio.dev/api/v3.1/connected_accounts/ca_abc123 \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"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](https://composio-preview.mintlify.site/docs/auth-configuration/connected-accounts.md#list-accounts).

> [tab] Python
>
> ```python theme={null}
> session = composio.create(
>     user_id="user_123",
>     connected_accounts={
>         "gmail": ["ca_work_gmail_id"],
>         "github": ["ca_personal_github_id"],
>     },
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123", {
>   connectedAccounts: {
>     gmail: ["ca_work_gmail_id"],
>     github: ["ca_personal_github_id"],
>   },
> });
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tool_router/session \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "user_id": "user_123",
>     "connected_accounts": {"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:

> [tab] Python
>
> ```python theme={null}
> 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}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const session = await composio.create("user_123");
> const toolkits = await session.toolkits();
>
> for (const toolkit of toolkits.items) {
>   if (toolkit.connection?.connectedAccount) {
>     console.log(`${toolkit.name}: ${toolkit.connection.connectedAccount.id}`);
>   }
> }
> ```

> [tab] API
>
> ```bash theme={null}
> # SESSION_ID is the session_id returned when you created the session
> curl -s -X GET https://backend.composio.dev/api/v3.1/tool_router/session/$SESSION_ID/toolkits \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   | jq -r '.items[] | select(.connected_account) | "\(.name): \(.connected_account.id)"'
> ```

## Next

> [card] [Shared connections](https://composio-preview.mintlify.site/docs/extending-sessions/shared-connections.md)
>
> Make one connected account usable by multiple users with a per-user access control list
