Injecting Custom Credentials

While Composio excels at managing user connections via Integrations and the connection flow, there are scenarios where you might need to provide authentication credentials directly when executing an action. This bypasses Composio’s stored Connections entirely.

This is achieved using the auth parameter within the execute_action method.

The auth parameter in execute_action

When calling execute_action, you can include an auth object (Python dict / TS object) to specify the credentials Composio should use for that specific API call. This overrides any attempt Composio would normally make to look up credentials based on entity_id or connected_account_id.

The core of the auth object is the parameters list, which defines the credentials and how they should be injected into the API request.

CustomAuthParameter Structure:

Each item in the parameters list should be an object with:

• name: (str) The name of the credential parameter (e.g., "Authorization", "X-Api-Key", "api_key").
• value: (str) The actual secret value (e.g., "Bearer xyz...", "sk-abc...").
• in_ (Python) / in (TS): (str or ParamPlacement) Where to place the parameter in the HTTP request. Common values include:
  • "header" / ParamPlacement.Header: In the request headers.
  • "query" / ParamPlacement.Query: As a URL query parameter.
  • "path" / ParamPlacement.Path: As part of the URL path (less common for auth).
  • "subdomain" / ParamPlacement.Subdomain: As part of the subdomain.

(Optional fields like base_url and body can also exist within the top-level auth object for very specific authentication schemes, but parameters is the most common.)

Adding Custom Authentication to Tools

You can also execute any Composio tool (pre-built or custom-defined) using your own authentication credentials provided at runtime. This is useful if you manage tokens or API keys separately from Composio’s connection system.

Use the execute_action method and provide the auth parameter.

Example: Create GitHub Issue with a Provided Token

1
# Python example providing a custom Bearer token
2
from composio import ComposioToolSet, Action
3
4
toolset = ComposioToolSet()
5
bearer_token = "ghp_YourPersonalAccessToken..." # Replace with your actual token
6
7
print("Creating issue using custom auth...")
8
try:
9
    result = toolset.execute_action(
10
        action=Action.GITHUB_CREATE_ISSUE,
11
        params={
12
            "owner": "your-username",
13
            "repo": "test-repo",
14
            "title": "Issue Created with Custom Token",
15
            "body": "This issue uses an externally provided auth token."
16
        },
17
        # Provide authentication details via the 'auth' parameter
18
        auth={
19
            "parameters": [
20
                {
21
                    "name": "Authorization", # Header name
22
                    "value": f"Bearer {bearer_token}", # Header value
23
                    "in_": "header" # Placement (header, query, path, etc.)
24
                }
25
            ]
26
            # 'base_url' could be added here for GitHub Enterprise
27
            # 'body' could be added for complex auth flows if needed
28
        }
29
        # entity_id is typically not needed when providing full custom auth
30
    )
31
    print(result)
32
except Exception as e:
33
    print(f"An error occurred: {e}")