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!

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

OAuth Connections

OAuth connections redirect users to the toolkit’s login page. Popular toolkits that use OAuth authentication include: Gmail, Notion etc.

Here’s how to initiate the flow:

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 = "ac_UdqFwixfy3cV"
7
8
# Use a unique identifier for each user in your application
9
user_id = "user_123"
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
)
16
17
# Redirect user to this URL
18
print(f"Redirect URL: {connection_request.redirect_url}")
19
20
connected_account = connection_request.wait_for_connection()
21
22
# Alternative: if you only have the connection request ID
23
# connected_account = composio.connected_accounts.wait_for_connection(
24
#     connection_request.id)
25
# Recommended when the connection_request object is no longer available
26
27
print(f"Connection established: {connected_account.id}")

Redirecting Users (OAuth only)

For OAuth flows, you can control where users are redirected after authentication by providing a callback Url:

1
connection_request = composio.connected_accounts.initiate(
2
    user_id=user_id,
3
    auth_config_id=auth_config_id,
4
    config={"auth_scheme": "OAUTH2"},
5
    callback_url="https://www.yourapp.com/callback"
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 = "ac_ZUWpt850AqTN"
7
# Use a unique identifier for each user in your application  
8
user_id = "user_12323"
9
# API key provided by the user (collected from your app's UI)
10
# or use your own key
11
user_api_key = "user_api_key_here"
12
13
connection_request = composio.connected_accounts.initiate(
14
    user_id=user_id,
15
    auth_config_id=auth_config_id,
16
    config={
17
        "auth_scheme": "API_KEY", "val": {"api_key": user_api_key}
18
    }
19
)
20
21
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 = "ac_ZUWpt850AqTN"
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.