Authenticating Tools

The first step in authenticating your Users is to create an Auth Config. Every toolkit has its own authentication method such as OAuth, API key, Basic Auth, or custom schemes.

An Auth Config is a blueprint that defines how authentication works for a toolkit across all your users. It defines:

1. Authentication method - OAuth2, Bearer token, API key, or Basic Auth
2. Scopes - what actions your tools can perform
3. Credentials - whether you’ll use your own app credentials or Composio’s managed auth

Creating an auth config

Using the Dashboard

When to create multiple auth configs?

You should create multiple auth configs for the same toolkit when you need:

• Different authentication methods - One OAuth config and one API key config
• Different scopes - Separate configs for read-only vs full access
• Different OAuth apps - Using separate client credentials for different environments
• Different permission levels - Limiting actions for specific use cases

Connecting an account

With an auth config created, you’re ready to authenticate your users!

You can either use Connect Link for a hosted authentication flow, or use Direct SDK Integration.

Choose the section below that matches your toolkit’s authentication method:

Hosted Authentication (Connect Link)

Redirect users to a Composio-hosted URL that handles the entire authentication process—OAuth flows, API key collection, or custom fields like subdomain. You can specify a callback URL to control where users return after authentication.

1
from composio import Composio
2
3
composio = Composio(api_key="your_api_key")
4
5
# Use the "AUTH CONFIG ID" from your dashboard
6
auth_config_id = "your_auth_config_id"
7
8
# Use a unique identifier for each user in your application
9
user_id = 'user-1349-129-12'
10
11
connection_request = composio.connected_accounts.link(user_id, auth_config_id, callback_url: 'https://your-app.com/callback')
12
13
redirect_url = connection_request.redirect_url
14
print(f"Visit: {redirect_url} to authenticate your account")
15
            
16
# Wait for the connection to be established
17
connected_account = connection_request.wait_for_connection()
18
print(connected_account.id)

Customizing Connect Link

By default, users will see a Composio-branded authentication experience when connecting their accounts. To customize this interface with your application’s branding:

1. Navigate to your Project Settings and select Auth Screen
2. Configure your Logo and App Title

These settings will apply to all authentication flows using Connect Link, providing a white-labeled experience that maintains your brand identity throughout the authentication process.

Direct SDK Integration

Choose the section below that matches your toolkit’s authentication method:

OAuth Connections

For OAuth flows, you’ll redirect users to complete authorization. You can specify a callback URL to control where users return after authentication:

1
from composio import Composio
2
3
composio = Composio(api_key="YOUR_COMPOSIO_API_KEY")
4
5
# Use the "AUTH CONFIG ID" from your dashboard
6
auth_config_id = "your_auth_config_id"
7
8
# Use a unique identifier for each user in your application
9
user_id = "user-1349-129-12"
10
11
connection_request = composio.connected_accounts.initiate(
12
  user_id=user_id,
13
  auth_config_id=auth_config_id,
14
  config={"auth_scheme": "OAUTH2"},
15
  callback_url="https://www.yourapp.com/callback"
16
)
17
print(f"Redirect URL: {connection_request.redirect_url}")
18
19
connected_account = connection_request.wait_for_connection()
20
21
# Alternative: if you only have the connection request ID
22
# connected_account = composio.connected_accounts.wait_for_connection(
23
#  connection_request.id)
24
# Recommended when the connection_request object is no longer available
25
26
print(f"Connection established: {connected_account.id}")

Services with Additional Parameters

Some services like Zendesk require additional parameters such as subdomain:

1
# For Zendesk - include subdomain
2
connection_request = composio.connected_accounts.initiate(
3
  user_id=user_id,
4
  auth_config_id=auth_config_id,
5
  config=auth_scheme.oauth2(subdomain="mycompany")  # For mycompany.zendesk.com
6
)

API Key Connections

For API key authentication, you can either collect API keys from each user or use your own API key for all users. Popular Toolkits that use API Keys include Stripe, Perplexity etc.

Here is how to initiate the flow:

1
from composio import Composio
2
3
composio = Composio(api_key="your_api_key")
4
5
# Use the "AUTH CONFIG ID" from your dashboard
6
auth_config_id = "your_auth_config_id"
7
8
# Use a unique identifier for each user in your application
9
user_id = "user_12323"
10
11
# API key provided by the user (collected from your app's UI)
12
# or use your own key
13
user_api_key = "user_api_key_here"
14
15
connection_request = composio.connected_accounts.initiate(
16
  user_id=user_id,
17
  auth_config_id=auth_config_id,
18
  config={
19
    "auth_scheme": "API_KEY", "val": {"api_key": user_api_key}
20
  }
21
)
22
23
print(f"Connection established: {connection_request.id}")

Fetching the required config parameters for an Auth Config

When working with any toolkits, you can inspect an auth config to understand its authentication requirements and expected parameters.

Here is how you would fetch the authentication method and input fields:

1
from composio import Composio
2
3
composio = Composio(api_key="your_api_key")
4
5
# Use the "AUTH CONFIG ID" from your dashboard
6
auth_config_id = "your_auth_config_id"
7
8
# Fetch the auth configuration details
9
auth_config = composio.auth_configs.get(auth_config_id)
10
11
# Check what authentication method this config uses
12
print(f"Authentication method: {auth_config.auth_scheme}")
13
14
# See what input fields are required
15
print(f"Required fields: {auth_config.expected_input_fields}")

Other Authentication Methods

Composio also supports a wide range of other auth schemas:

Bearer Token - Similar to API keys, provide the user’s bearer token directly when creating the connection.

Basic Auth - Provide username and password credentials for services that use HTTP Basic Authentication.

Custom Schemes - Some toolkits use their own custom authentication methods. Follow the toolkit-specific requirements for such cases.

Next Step

With authentication set up, you can now fetch and execute tools. See Executing Tools to get started.