Connecting to Token/API Key Apps

This guide covers the connection process for external apps that use authentication methods like static API Keys, Bearer Tokens, or other credentials that the end-user must provide (e.g., OpenAI, Stripe, Twilio, many database connections).

Unlike OAuth, this flow doesn’t typically involve redirecting the user’s browser. Instead, your application securely collects the necessary credentials from the user and passes them to Composio during the connection setup.

Prerequisites:

• An Integration for the target app must be configured in Composio, specifying the correct authentication scheme (e.g., API_KEY, BEARER_TOKEN).
• A unique entity_id representing the user within your application.

Token/API Key Connection Flow

Step 1: Discover Required Fields

Before prompting your user, determine exactly which credentials they need to provide. Use get_expected_params_for_user (Python) or apps.getRequiredParamsForAuthScheme (TypeScript) to query Composio.

1
from composio_openai import ComposioToolSet, App
2
3
toolset = ComposioToolSet()
4
5
# Replace with your actual integration ID
6
YOUR_INTEGRATION_ID = "int_shopify_xxxxxxxx..."
7
8
auth_scheme_for_shopify = "API_KEY"  # Check Integration config or Tool Directory
9
try:
10
    required_info = toolset.get_expected_params_for_user(
11
        app=App.SHOPIFY, auth_scheme=auth_scheme_for_shopify, integration_id=YOUR_INTEGRATION_ID
12
    )
13
    field_names = [field["name"] for field in required_info["expectedInputFields"]]
14
    print(f"Required fields for {App.SHOPIFY.value} ({auth_scheme_for_shopify}): {field_names}")
15
    # Use required_info["expectedInputFields"] for descriptions to show the user
16
except Exception as e:
17
    print(f"Error fetching required params: {e}")

This tells your application which fields (e.g., api_key, account_sid, token) to request from the user.

Step 2: Securely Collect Credentials from User

Your application’s UI must now prompt the user to enter the credentials identified in Step 1.

Step 3: Initiate Connection with User Credentials

Call initiate_connection (Python) or initiateConnection (TypeScript) on the user’s Entity object. Provide the integration_id (or app_name) and entity_id. Crucially, pass the credentials collected from the user inside the connected_account_params (Python) or connectionParams (TypeScript) dictionary.

1
user_id = "user_shopify_456"
2
3
# Assume user provided this value securely via your UI
4
user_provided_shopify_key = "sk_live_xxxxxxxxxxxxxxx"
5
6
# Assume entity and integration ID are known
7
# entity = toolset.get_entity(id="user_stripe_456")
8
SHOPIFY_INTEGRATION_ID = "int_shopify_yyyyyyyy..."
9
10
try:
11
    print(f"Initiating Shopify connection for entity {user_id}...")
12
    connection_request = toolset.initiate_connection(
13
        integration_id=SHOPIFY_INTEGRATION_ID, # Or app_name=App.SHOPIFY
14
        entity_id=user_id,
15
        auth_scheme="API_KEY", # Must match the integration's config
16
        # Pass the user-provided key(s) here
17
        connected_account_params={
18
            "api_key": user_provided_shopify_key
19
            # Add other fields if the app requires more (e.g., account_id)
20
        },
21
    )
22
    print("Connection initiation response:", connection_request)
23
    # Status should be ACTIVE almost immediately
24
    # connection_id = connection_request.connectedAccountId
25
26
except Exception as e:
27
    print(f"Error initiating connection: {e}")

Step 4: Connection Activation (Immediate)

For these types of connections, the connectionStatus in the response from initiate_connection should usually be ACTIVE immediately, as no external user authorization step is needed. The redirectUrl will typically be null.

You can optionally fetch the connection details using the connectedAccountId from the response to confirm the ACTIVE status before proceeding.

Once active, the Connection is ready, and you can use the entity_id or connectedAccountId to execute actions for this user and app.