Authenticating Tools

Different apps (like Slack, Notion, Shopify) have their own authentication flows that users must complete to grant access to their accounts. Agents need authenticated access to these tools to perform actions on behalf of users.

Creating an auth config

Each toolkit comes with its own auth config. This configuration is used to authenticate the users to the tools.

The first step is to create an auth config for any toolkit that you want to use.

The dashboard offers a guided process for all app types.

1

Select App

Navigate to the Apps page and choose the app you want to integrate (for example, Google Sheets).

2

Initiate Setup

Click the “Setup Integration” button.

3

Configure Auth Config Settings

Select among the supported auth schemes of OAuth2, API Key, Bearer Token, Basic Auth, depending on the toolkit. Switch between the auth schemes and configure the scopes, developer credentials, etc here.

Composio Managed Auth

You may also choose to use Composio’s managed auth for certain toolkits or use your own auth credentials. It is recommended to specify your own credentials for production workloads and ability to control scopes, etc.

4

Create and Get auth config ID

Click “Create Integration”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connecting to an OAuth toolkit

Here’s how to authenticate a toolkit for a given user using the OAuth flow.

1
from composio import Composio
2
from composio.types import auth_scheme
3
4
linear_auth_config_id = "ac_dqYN9oElNVlg"
5
user_id = "0000-1111-2222"
6
composio = Composio()
7
8
# Create a new connected account
9
connection_request = composio.connected_accounts.initiate(
10
    user_id=user_id, auth_config_id=linear_auth_config_id, config={"auth_scheme": "OAUTH2"}
11
)
12
print(connection_request.redirect_url)
13
14
# Wait for the connection to be established
15
connected_account = connection_request.wait_for_connection()
16
17
# If you only have the connection request ID, you can also wait using:
18
19
connected_account = composio.connected_accounts.wait_for_connection(connection_request.id)
20
# Recommended for when connection_request object is destroyed

Connecting to an API Key toolkit

For API key based toolkits, you can either request the user to provide the API key or provide your own!

Creating the connection

If you know the required authentication fields for your toolkit (like apiKey for most API-based services), you can directly create the connection:

1
# from composio.types import auth_scheme
2
serp_auth_config_id = "ac_VWmFEC55Zgv6"
3
4
# Retrieved from the user
5
user_api_key = "sk_1234567890"
6
7
connection_request = composio.connected_accounts.initiate(
8
    user_id=user_id,
9
    auth_config_id=serp_auth_config_id,
10
    config={"auth_scheme": "API_KEY", "val": user_api_key},
11
)

Specifying auth schemes

Composio supports a wide range of auth schemes; OAuth2, API Key, HTTP Basic and many more. Each app (and toolkit) has different connection options required for each auth scheme. For example;

• Shopify requires an API key from each user for the API Key auth scheme.
• Airtable requires the Bearer token from each user for the Bearer auth scheme.

The auth scheme information is typed and can be configured as follows:

1
# Auth scheme config for Airtable Bearer
2
# from composio.types import auth_scheme
3
airtable_auth_config_id = "ac_1234567"
4
5
# Retrieved from user
6
user_bearer_token = "1234567890"
7
8
airtable_connection_req = composio.connected_accounts.initiate(
9
    user_id=user_id,
10
    auth_config_id=airtable_auth_config_id,

It might be useful to read all the optional and required auth config fields for a toolkit and optionally prompt the user for the values.

Redirecting users

To control where the users are redirected after they have authenticated, you can use the redirectUrl parameter in the initiate method. In this case, the user will be redirected to https://www.yourapp.com/callback after they have authenticated.

1
connection_request = composio.connected_accounts.initiate(
2
    user_id=user_id, auth_config_id=linear_auth_config_id, config=auth_scheme.oauth2()
3
)
4
print(connection_request.redirect_url)
5
6
# Wait for the connection to be established
7
connected_account = connection_request.wait_for_connection()