Auth Lifecycle

Integrations

Integrations are configuration objects that store credentials and settings for specific APIs. They store the following properties, among others:

Configuring an integration

Typically you only need to create an integration once. That integration can be used by multiple users (called entities in Composio).

Each entity connects to an integration using a connection.

$
composio add github
>
>
# > Adding integration: Github...
>
>
# Please authenticate github in the browser and come back here. URL: https://backend.composio.dev/s/tizSmu22
>
# ⚠ Waiting for github authentication...
>
# ✔ github added successfully with ID: 00000000-0000-0000-0000-000000000000

Connections

A connection in Composio is an object that stores and manages your users’ authentication state and details for a specific app (integration).

An integration can have multiple connections, each representing a different user’s authentication state.

Creating a connection

Assuming the integration has been created and the ID is known, you can initiate a connection with the following code:

1
from composio_openai import ComposioToolSet, Action, App
2
3
toolset = ComposioToolSet()
4
5
user_id = "alice"
6
7
connection_req = toolset.initiate_connection(
8
    integration_id=GMAIL_INTEGRATION_ID,
9
    entity_id=user_id,
10
)
11
print(f"Navigate to {connection_req.redirectUrl} to connect your Gmail account")
12
print(f"Connection status: {connection_req.status}")    # Status will be INITIATED
13
14
connection = connection_req.wait_until_active(toolset.client, timeout=20)
15
16
print(f"Connection created: {connection.id}")

You can view the parameters for creating a connection here

Checking the status of a connection

Checking for status of a connection is useful to keep track of the authentication flow. This is especially useful for OAuth based flows.

1
entity = toolset.getEntity("default")   # An entity is required to get a connection
2
3
connection = entity.get_connection(app=App.GMAIL)
4
print(connection.status)

The valid connection states are:

• ACTIVE
• INACTIVE
• DELETED
• INITIATED
• EXPIRED

Getting connection details

You can get the details of a connection to inspect the connection parameters.

1
connection = toolset.get_connected_account(connection_id)
2
print(connection)
3
4
# Alternatively, you can get the connection details from the entity
5
6
entity = toolset.getEntity("default")
7
connection = entity.get_connection(app=App.GMAIL)
8
print(connection)

1
{
2
    "id": "********",
3
    "status": "ACTIVE", 
4
    "createdAt": "2025-03-28T06:18:57.611Z",
5
    "updatedAt": "2025-03-28T11:21:55.679Z",
6
    "appUniqueId": "gmail",
7
    "appName": "gmail",
8
    "integrationId": "********",
9
    "connectionParams": {
10
        "scope": "********",
11
        "base_url": "https://www.googleapis.com",
12
        "client_id": "********",
13
        "token_type": "********", 
14
        "access_token": "********",
15
        "refresh_token": "********",
16
        "client_secret": "********",
17
        "consumer_id": null,
18
        "consumer_secret": null,
19
        "headers": {
20
            "Authorization": "********",
21
            "x-request-id": "********"
22
        },
23
        "queryParams": {}
24
    },
25
    "clientUniqueUserId": "default",
26
    "entityId": "default"
27
}

Deleting a connection

Deleting a connection is useful to remove a connection from the system. Typically done when a user wants to disconnect from an app or no longer wishes to give access to an app.

1
const res =  toolset.client.connectedAccounts.delete({
2
    connectedAccountId: "********",
3
})
4
5
console.log(res)