Connected Accounts | Composio Docs

Connected accounts are authenticated connections between your users and toolkits. After users authenticate (see Authenticating tools), you can manage these accounts throughout their lifecycle.

Composio automatically handles token refresh and credential management. This guide covers manual operations: listing, retrieving, refreshing, enabling, disabling, and deleting accounts.

List accounts

Retrieve all connected accounts with optional filters:

1 # List all accounts for a user
2 accounts = composio.connected_accounts.list(
3     user_ids=[user_id]
4 )
5 
6 # Filter by status
7 active_accounts = composio.connected_accounts.list(
8     user_ids=[user_id],
9     statuses=["ACTIVE"]
10 )

Get account details

Retrieve a connected account by ID:

1 account = composio.connected_accounts.get(connected_account_id)
2 
3 print(f"Status: {account.status}")
4 print(f"Toolkit: {account.toolkit.slug}")

Get account credentials

Get account credentials for use with your own tools:

1 # Get the connected account's authentication state
2 if account.state:
3     # The state contains the auth scheme and credentials
4     auth_scheme = account.state.auth_scheme
5     credentials = account.state.val
6     
7     print(f"Auth scheme: {auth_scheme}")
8     print(f"Credentials: {credentials}")

Refresh credentials

Manually refresh credentials for a connected account:

1 try:
2     refreshed = composio.connected_accounts.refresh(connected_account_id)
3     print(f"Redirect URL: {refreshed.redirect_url}")
4     
5     # Wait for the connection to be established
6     composio.connected_accounts.wait_for_connection(refreshed.id)
7 except Exception as e:
8     print(f"Failed to refresh tokens: {e}")

Enable and disable accounts

Change account status without deleting. Set to INACTIVE to pause access, or ACTIVE to restore. Useful for:

Pausing access during subscription lapses
Temporary disconnection

1 # Disable an account
2 disabled = composio.connected_accounts.disable(connected_account_id)
3 print(f"Account disabled status: {disabled.success}")
4 
5 # Re-enable when needed
6 enabled = composio.connected_accounts.enable(connected_account_id)
7 print(f"Account enabled status: {enabled.success}")

INACTIVE accounts cannot execute tools. Tool execution will fail until the status is changed.

Delete accounts

Permanently remove a connected account and revoke all credentials:

1 # Delete a connected account
2 composio.connected_accounts.delete(connected_account_id)
3 print("Account deleted successfully")

Deletion is permanent. Users must re-authenticate to reconnect.

Multiple accounts

Users can connect multiple accounts for the same toolkit (e.g., personal and work Gmail).

Use link() for creating accounts, as it provides hosted authentication and allows multiple accounts by default. See Connect Link authentication.

1 # First account
2 try:
3     first_account = composio.connected_accounts.initiate(
4         user_id=user_id,
5         auth_config_id=auth_config_id
6     )
7     print(f"First account redirect URL: {first_account.redirect_url}")
8     connected_first_account = first_account.wait_for_connection()
9     print(f"First account status: {connected_first_account.status}")
10 except Exception as e:
11     print(f"Error initiating first account: {e}")
12 
13 # Second account - must explicitly allow multiple
14 try:
15     second_account = composio.connected_accounts.initiate(
16         user_id=user_id,
17         auth_config_id=auth_config_id,
18         allow_multiple=True  # Required for additional accounts
19     )
20     print(f"Second account redirect URL: {second_account.redirect_url}")
21     connected_second_account = second_account.wait_for_connection()
22     print(f"Second account status: {connected_second_account.status}")
23 except Exception as e:
24     print(f"Error initiating second account: {e}")

Execute with a specific account

When you have multiple accounts, specify which one to use with connected_account_id:

1 # Execute tool with a specific connected account
2 result = composio.tools.execute(
3     "GMAIL_GET_PROFILE",
4     user_id=user_id,
5     connected_account_id=connected_account_id,  # Specify which account to use
6     version="20251111_00",
7     arguments={}
8 )