Users and sessions

A user ID is an identifier from your system (database ID, UUID, or any unique string) that scopes connected accounts and tool access to a specific user. User IDs can represent individuals, teams, or organizations. See User Management for patterns.

A session is an ephemeral configuration that combines:

• Which user’s connected accounts to use
• Which toolkits are available
• Which auth configs to use

Tool Router’s meta-tools are the same for everyone. The session determines the context they operate within.

Creating a session

1
session = composio.create(user_id="user_123")

Enabling toolkits

Restrict the session to specific toolkits:

1
# Using array format
2
session = composio.create(
3
    user_id="user_123",
4
    toolkits=["github", "gmail", "slack"]
5
)
6
7
# Using object format with enable key
8
session = composio.create(
9
    user_id="user_123",
10
    toolkits={"enable": ["github", "gmail", "slack"]}
11
)

Disabling toolkits

Keep all toolkits enabled except specific ones:

1
session = composio.create(
2
    user_id="user_123",
3
    toolkits={"disable": ["exa", "firecrawl"]}
4
)

Custom auth configs

Use your own OAuth credentials instead of Composio’s defaults:

1
session = composio.create(
2
    user_id="user_123",
3
    auth_configs={
4
        "github": "ac_your_github_config",
5
        "slack": "ac_your_slack_config"
6
    }
7
)

See White-labeling authentication for branding, or Using custom auth configs for toolkits that require your own credentials.

Connected accounts

Connected accounts are stored in Composio and persist across sessions. When a user connects their GitHub account in one session, it remains available in future sessions. Sessions configure which connections to use, but don’t own the connections themselves.

Account selection

If a user has multiple connected accounts for the same toolkit, you can specify which one to use:

1
session = composio.create(
2
    user_id="user_123",
3
    connected_accounts={
4
        "gmail": "ca_work_gmail",
5
        "github": "ca_personal_github"
6
    }
7
)

Precedence

When executing a tool, Tool Router selects the connected account in this order:

1. connectedAccounts override if provided in session config
2. authConfigs override - finds or creates connection on that config
3. Auth config previously created by Tool Router for this toolkit
4. Creates new auth config using Composio managed auth (tagged as Tool Router created)
5. Error if no Composio managed auth scheme exists for the toolkit

If a user has multiple connected accounts for a toolkit, the most recently connected one is used.

Session methods

mcp

Get the MCP server URL to use with any MCP-compatible client.

1
mcp_url = session.mcp.url

For framework examples, see Using with MCP clients or Using as a native tool.

tools()

Get native tools from the session for use with AI frameworks.

1
tools = session.tools()

authorize()

Manually authenticate a user to a toolkit outside of the chat flow.

1
connection_request = session.authorize("github")
2
3
print(connection_request.redirect_url)
4
5
connected_account = connection_request.wait_for_connection()

For more details, see Manually authenticating users.

toolkits()

List available toolkits and their connection status. You can use this to build a UI showing which apps are connected.

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

Returns the first 20 toolkits by default.