Authentication and Integrations

Overview

As agents move closer to the user, they need access to the user’s data and services to perform tasks with agency. Connecting these agents and applications to third party services means having the manage the complexities of authentication yourself.

Integrations

An integration is a configuration object that defines how an application connects to external service for a user. It encapsulates the authentication credentials, permission scopes and API specification that determine how an AI agent interacts with the external service.

Using Composio’s client credentials (for prototyping)

It’s a development overhead and a burden to manage and create a developer app when making AI Agents for personal use or during prototyping.

To solve for that, you can use Composio’s client credentials.

1
from composio_openai import ComposioToolSet, App, Action
2
3
toolset = ComposioToolSet()
4
integration = toolset.create_integration(
5
    app=App.GITHUB,
6
    auth_mode="OAUTH2",
7
    use_composio_oauth_app=True,
8
    force_new_integration=True,
9
)

Creating and using your own developer app

1
from composio_openai import ComposioToolSet, App, Action
2
3
toolset = ComposioToolSet()
4
toolset.create_integration(
5
    app=App.GITHUB,
6
    auth_mode="OAUTH2",
7
    force_new_integration=True,
8
    use_composio_oauth_app=False,
9
    auth_config={
10
        "client_id": "1234567890",
11
        "client_secret": "1234567890",
12
        "redirect_uri": "https://backend.yourapp.com/handle-redirect-uri/",
13
        "scopes": ["repo", "user"],
14
    },
15
)

Connections and entities

An entity represents a unique user in your application’s ecosystem. Think of it as a container that holds all the third-party service connections for a single user. Key points about entities:

For example, if you have a user “Alice” in your application, she would have a single entity ID that links to all her connected services (GitHub, Google Calendar, etc.).

A connection represents an authenticated link between an entity (user) and a specific external service through an integration. When a user authorizes your application to access a service, Composio:

1
# Using the above imports
2
user_id = "alice_id"    # Retrieved through application logic / DB
3
4
toolset.get_integration(id=integration.id)
5
entity = toolset.get_entity(id=user_id)
6
conn_req = entity.initiate_connection(app_name=App.GITHUB, use_composio_auth=True)
7
8
print(conn_req.redirectUrl) # Emit the redirect URL back to the user

During tool calling and execution, specifying the entity_id will execute the tool on behalf of the user specified.

Executing tool calls on behalf of the user

1
toolset.handle_tool_calls(
2
    response=response,
3
    entity_id=entity.id,
4
)