Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/ComposioHQ/composio/llms.txt

Use this file to discover all available pages before exploring further.

composio.connected_accounts is the interface for managing user connections to third-party services. Use it to initiate OAuth flows, import existing tokens, and query or delete connections. A connected account ties an external user ID to credentials for a specific toolkit (e.g. GitHub, Gmail, Slack) and is required before tools can be executed on that user’s behalf. Create a Composio Connect Link for a user to authorize a connection via OAuth. Returns a ConnectionRequest that contains a redirect_url to send the user to. 
def link(
    user_id: str,
    auth_config_id: str,
    *,
    callback_url: str | None = None,
    alias: str | None = None,
    allow_multiple: bool = False,
    experimental: link_create_params.Experimental | None = None,
) -> ConnectionRequest
​
user_id
str
required
Your application’s external user identifier. Composio uses this to associate the connection with the correct user for tool execution.
​
auth_config_id
str
required
The ID of the auth config (ac_xxx) that defines which OAuth application and scopes to use. Retrieve this from composio.auth_configs.list() or the Composio dashboard.
​
callback_url
str
URL to redirect the user to after they complete the OAuth flow in the external service. Overrides the default callback URL configured on the auth config.
​
alias
str
Optional human-readable label for this connection (e.g. "work-github"). Must be unique per user_id and toolkit within the project.
​
allow_multiple
bool
When False (default), raises ComposioMultipleConnectedAccountsError if the user already has an ACTIVE connection on this auth config. Set to True to allow multiple connections.
​
experimental
Experimental
Experimental options for creating SHARED connections with per-user ACL configuration. Shape may change in future releases.

​
connected_accounts.initiate()

initiate() is deprecated for Composio-managed OAuth flows. Use link() instead, which works for all redirectable schemes and has the same return shape. initiate() continues to work for custom auth configs and non-OAuth schemes (API key, bearer token, basic auth).
def initiate(
    user_id: str,
    auth_config_id: str,
    *,
    callback_url: str | None = None,
    allow_multiple: bool = False,
    config: connected_account_create_params.ConnectionState | None = None,
    alias: str | None = None,
) -> ConnectionRequest
​
user_id
str
required
The external user ID to create the connected account for.
​
auth_config_id
str
required
The auth config ID (ac_xxx) specifying which OAuth app to use.
​
callback_url
str
Callback URL for OAuth redirect flows.
​
allow_multiple
bool
Allow multiple active connections for the same user and auth config. Default False.
​
config
ConnectionState
A typed connection state dict (produced by auth_scheme.oauth2(...), auth_scheme.api_key(...), etc.) for importing existing credentials without a redirect flow.
​
alias
str
Optional human-readable alias for the connection.

​
connected_accounts.get()

Retrieve a single connected account by its ID. 
def get(nanoid: str) -> ConnectedAccountRetrieveResponse
​
nanoid
str
required
The connected account ID (ca_xxx).

​
connected_accounts.list()

List connected accounts with optional filters. 
def list(
    *,
    user_ids: list[str] | None = None,
    toolkit_slugs: list[str] | None = None,
    auth_config_ids: list[str] | None = None,
    statuses: list[str] | None = None,
    limit: int | None = None,
    cursor: str | None = None,
) -> ConnectedAccountListResponse
​
user_ids
list[str]
Filter to connections belonging to specific user IDs.
​
toolkit_slugs
list[str]
Filter to connections for specific toolkits (e.g. ["github", "gmail"]).
​
auth_config_ids
list[str]
Filter to connections using specific auth configs.
​
statuses
list[str]
Filter by status. Values: "ACTIVE", "INACTIVE", "FAILED", "EXPIRED", "REVOKED".
​
limit
int
Maximum number of results to return per page.
​
cursor
str
Pagination cursor. Pass next_cursor from the previous response to get the next page.

​
connected_accounts.delete()

Delete a connected account permanently. 
def delete(nanoid: str) -> None
​
nanoid
str
required
The connected account ID (ca_xxx) to delete.

​
connected_accounts.update()

Update a connected account’s alias or credentials. 
def update(
    nanoid: str,
    *,
    alias: str | None = None,
    connection: connected_account_patch_params.Connection | None = None,
) -> ConnectedAccountPatchResponse
​
nanoid
str
required
The connected account ID (ca_xxx).
​
alias
str
New human-readable alias. Pass an empty string "" to clear the current alias.
​
connection
Connection
Credential update payload with authScheme and val fields.

​
connected_accounts.wait_for_connection()

Poll until a connected account becomes ACTIVE or a timeout is reached. 
def wait_for_connection(
    id: str,
    timeout: float | None = None,
) -> ConnectedAccountRetrieveResponse
​
id
str
required
The connected account ID (ca_xxx) to wait on.
​
timeout
float
Maximum seconds to wait. Defaults to 60.0. Raises ComposioSDKTimeoutError on expiry.

​
ConnectionRequest

link() and initiate() both return a ConnectionRequest object.
​
id
str
The connected account ID (ca_xxx). Use this with wait_for_connection().
​
status
str
Current connection status (e.g. "INITIATED", "ACTIVE", "FAILED").
​
redirect_url
str | None
The OAuth authorization URL to redirect the user to. None for non-redirect flows (API key, bearer token, etc.).

​
connection_request.wait_for_connection(timeout=60)

Wait on the ConnectionRequest object directly instead of passing the ID: 
def wait_for_connection(timeout: float | None = None) -> ConnectedAccountRetrieveResponse

​
auth_scheme helpers

The auth_scheme singleton (from composio.core.models.connected_accounts) produces typed ConnectionState dicts for importing credentials directly without a redirect flow. Use these with initiate(config=...). 
from composio.core.models.connected_accounts import auth_scheme

# Import an existing OAuth 2 token
state = auth_scheme.oauth2({"access_token": "gho_xxx", "refresh_token": "ghr_xxx"})

# Register an API key credential
state = auth_scheme.api_key({"api_key": "sk-xxx"})

# Bearer token
state = auth_scheme.bearer_token({"token": "Bearer xxx"})
Available helpers: oauth1, oauth2, composio_link, api_key, basic, bearer_token, google_service_account, no_auth, calcom_auth, billcom_auth, basic_with_jwt.

​
Code examples

​
OAuth flow with redirect

import os
from composio import Composio

composio = Composio(api_key=os.environ["COMPOSIO_API_KEY"])

# Start the OAuth flow
connection_request = composio.connected_accounts.link(
    user_id="user_123",
    auth_config_id="ac_xxxxxxxxxxxx",
    callback_url="https://your-app.com/oauth/callback",
)

# Redirect the user
print(f"Visit: {connection_request.redirect_url}")

# Later, after the user completes auth — poll until active
connected_account = connection_request.wait_for_connection(timeout=120)
print(f"Connected! Account ID: {connected_account.id}")

​
Import an existing API key

from composio.core.models.connected_accounts import auth_scheme

connection_request = composio.connected_accounts.initiate(
    user_id="user_123",
    auth_config_id="ac_xxxxxxxxxxxx",
    config=auth_scheme.api_key({"api_key": "my-service-api-key"}),
)

# API key connections are ACTIVE immediately — no redirect needed
connected_account = connection_request.wait_for_connection(timeout=10)

​
List and filter connections

# All active GitHub connections for a user
connections = composio.connected_accounts.list(
    user_ids=["user_123"],
    toolkit_slugs=["github"],
    statuses=["ACTIVE"],
)

for account in connections.items:
    print(account.id, account.status, account.created_at)

Build docs developers (and LLMs) love

Get started for freeTalk to us