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 an existing Bearer Token

1
# Python example providing a custom Bearer token
2
from composio_openai import ComposioToolSet, Action, App
3
from composio.client.collections import CustomAuthParameter
4
5
toolset = ComposioToolSet()
6
bearer_token = "ghp_YourPersonalAccessToken..."  # Replace with your actual token
7
8
toolset.add_auth(
9
    app=App.GITHUB,
10
    parameters=[
11
        CustomAuthParameter(
12
            name="Authorization",
13
            in_="header",
14
            value=bearer_token,
15
        )
16
    ],
17
)
18
19
20
print("Creating issue using custom auth...")
21
try:
22
    result = toolset.execute_action(
23
        action=Action.GITHUB_CREATE_ISSUE,
24
        params={
25
            "owner": "your-username",
26
            "repo": "test-repo",
27
            "title": "Issue Created with Custom Token",
28
            "body": "This issue uses an externally provided auth token.",
29
        },
30
    )
31
    print(result)
32
except Exception as e:
33
    print(f"An error occurred: {e}")

Using DescopeAuth (for Descope)

You can also use DescopeAuth for simpler Descope integration.

To learn more, visit our Outbound Apps docs

1
from composio.utils.descope import DescopeAuth
2
3
# Initialize DescopeAuth with your credentials
4
descope = DescopeAuth(
5
    project_id="your_project_id",    # Or uses DESCOPE_PROJECT_ID env var
6
    management_key="your_management_key"  # Or uses DESCOPE_MANAGEMENT_KEY env var
7
)
8
9
toolset = ComposioToolSet()
10
11
# Add authentication using DescopeAuth
12
toolset.add_auth(
13
    app=App.GITHUB,
14
    parameters=descope.get_auth(
15
        app=App.GITHUB,
16
        user_id="your_user_id",
17
        scopes=["user", "public_repo"]  # Permissions for the token
18
    )
19
)

The DescopeAuth utility simplifies authentication with Descope by:

• Generating the necessary authentication tokens for external services
• Managing the authorization headers and metadata
• Setting appropriate scopes for the required permissions
• Managing tokens at both a user and tenant level
• Associating tokens with pre-existing app identities (using Descope as an auth provider)

Additional Context for DescopeAuth Usage

To use DescopeAuth, ensure you have the required project_id and management_key from your Descope account. These credentials are necessary to authenticate and generate the required headers for API calls. The scopes parameter defines the permissions for the generated token.