Users, auth configs and connected accounts

Every tool call runs as one of your users. A connected account is that user's authorised connection to an app; an auth config says how connections to that app are made.

Term	What it is	Example
user id	Your identifier for a user; Composio stores connections under it	`"cust_7f3a"`, your database id
toolkit	An app and its tools	`github`, `gmail`
auth config	How users connect to a toolkit: Composio's managed OAuth app or your own	`ac_...`
connected account	One user's live, authorised connection	`ca_...`

Examplewith a key

session = composio.create(user_id="cust_7f3a", toolkits=["github"])
request = session.authorize("github", callback_url="https://your-app.example/connected")
print(request.redirect_url)   # send the user here to sign in to GitHub
request.wait_for_connection()

Example

import inspect

from composio.core.models.connected_accounts import ConnectedAccounts
from composio.core.models.tool_router_session import ToolRouterSession

print(list(inspect.signature(ToolRouterSession.authorize).parameters)[1:])
print(list(inspect.signature(ConnectedAccounts.link).parameters)[1:])

Two ways to start a connection, from the installed SDK. session.authorize(toolkit) creates a sign-in link inside a session. composio.connected_accounts.link(user_id, auth_config_id) does it for a specific auth config, outside a session. Both return a ConnectionRequest whose redirect_url the user opens; Composio completes OAuth and stores the tokens.

User ids are a security boundary

Connections are stored under the id you pass, so use a stable database id, not an email that can change, and never one shared id such as default for everyone, which would let every user act through the same connections.

Try it yourself

Print the parameters of ConnectedAccounts.initiate.
Find ConnectionRequest in the SDK and list its fields.
Write down which user id your own app would pass, and where it comes from.

PreviousInstallation and setup

You understood something today that you didn't yesterday.