Connecting Users Overview

After setting up an Integration for an external app, the next step is to enable your individual end-users to authorize Composio to act on their behalf. This process creates a Connection.

It securely stores the user-specific credentials (like OAuth tokens or API keys) obtained during the authorization process. Every authenticated action executed via Composio happens through one of these Connections.

Identifying Your User: The entity_id

A fundamental concept when creating Connections is the entity_id.

• What: A unique ID that represents your end-user within Composio. Can map to DB/UUID in your app.
• Why: It allows Composio to use the correct credentials for your end-user in multi-tenant scenarios.
• Default: Composio uses the default ID "default". This is suitable only for single-user scripts, personal testing.

You will pass the entity_id when initiating the connection process using the SDK, typically by first getting an Entity object:

1
from composio_openai import ComposioToolSet, Action, App
2
3
toolset = ComposioToolSet()
4
user_identifier_from_my_app = "user_7a9f3b_db_id" # Example
5
6
# Get the Composio Entity object for your user
7
entity = toolset.get_entity(id=user_identifier_from_my_app)
8
# Use this 'entity' object to initiate connections

Initiating a Connection (Conceptual)

The process generally starts by calling initiate_connection (Python) or initiateConnection (TS) on the entity object, providing the integration_id or app_name.

1
# Conceptual initiation - details depend on auth type
2
connection_request = toolset.initiate_connection(
3
    integration_id=YOUR_INTEGRATION_ID, entity_id=user_identifier_from_my_app
4
)
5
# or
6
connection_request = toolset.initiate_connection(
7
    app_name=App.GITHUB, entity_id=user_identifier_from_my_app
8
)
9
10
toolset.execute_action(
11
    action=Action.GITHUB_CREATE_AN_ISSUE, params={...}, entity_id=user_identifier_from_my_app
12
)
13
14
toolset.execute_action(
15
    action=Action.GITHUB_CREATE_AN_ISSUE,
16
    params={...},
17
    entity_id=user_identifier_from_my_app
18
)

The specific steps that follow (handling redirects, waiting for activation, or providing parameters) depend heavily on whether the app uses OAuth or requires user-provided tokens.

Follow the detailed guides for your specific scenario:

• Connecting to OAuth Apps
• Connecting to Token/API Key Apps

Managing Existing Connections

Once connections are established, you can retrieve and manage them using the SDK.

• List Connections for a User: Get all active connections associated with a specific entity_id.

  PythonTypeScript

  1
  user_identifier_from_my_app = "user_7a9f3b_db_id"  # Example
  2
  entity = toolset.get_entity(id=user_identifier_from_my_app)
  3
  try:
  4
      connections = toolset.get_connected_accounts(entity_id=user_identifier_from_my_app) # Returns list of active connections
  5
      print(f"Found {len(connections)} active connections for {entity.id}:")
  6
      for conn in connections:
  7
          print(f"- App: {conn.appName}, ID: {conn.id}, Status: {conn.status}")
  8
      # You can also filter directly via the client:
  9
      # connections = toolset.client.connected_accounts.get(entity_ids=[entity.id], active=True)
  10
  except Exception as e:
  11
      print(f"Error fetching connections: {e}")

• Get a Specific Connection: Retrieve details using its unique connected_account_id.

  PythonTypeScript

  1
  connection_id = "1d28bbbb-91d0-4181-b4e5-088bab0d7779"
  2
  3
  connection = toolset.get_connected_account(connection_id)
  4
  print(f"Details for {connection.id}: App={connection.appName}, Status={connection.status}")