- Pre-authenticate users before they start chatting.
- Build a custom connections UI in your app.
Authorize a toolkit
Callsession.authorize() to generate a Connect Link URL, redirect the user, and wait for them to finish:
- Python
- TypeScript
- API
redirectUrl. After they authenticate, they’ll return to your callback URL. The connection request polls until the user completes authentication (default timeout: 60 seconds).
If the user closes the Connect Link without completing auth, the connection remains in
INITIATED status until it expires.Reusing an active connection
In TypeScript, callsession.ensureConnected("gmail") to reuse the session’s active connection. If none exists, it starts an authorization flow and waits for the connection to become active. The optional timeout sets how long to wait in milliseconds (default: 60000).
The result includes toolkit, wasConnected, and connectedAccount. wasConnected is true when an active connection already exists. Toolkits that don’t require authentication also return wasConnected: true, with no connectedAccount.
Use session.authorize() and waitForConnection() when you need to display or redirect to the Connect Link. ensureConnected() waits internally and doesn’t return the redirect URL. Calling authorize() always starts a new authorization flow, even if an active connection exists.
Redirecting users after authentication
Pass acallbackUrl to control where users land after authenticating. You can include query parameters to carry context through the flow, for example to identify which userID or session triggered the connection.
- Python
- TypeScript
- API
Identify the connected account
After authentication, use the account returned bywait_for_connection() or waitForConnection() to identify which provider account connected. If you use a callback instead, verify its connected_account_id against the connection attempt stored on your server and the signed-in application user before retrieving it. Callback query parameters alone aren’t proof of ownership.
These identifiers serve different purposes:
For a “Connected as…” label, read
state.val.displayName when available. For additional profile fields, get the toolkit’s current-user endpoint and call it through Composio’s authenticated proxy with the same connected account ID:
- Python
- TypeScript
- API
Check connection status
Usesession.toolkits() to see all toolkits in the session and their connection status:
- Python
- TypeScript
- API
Disabling in-chat auth
By default, sessions include theCOMPOSIO_MANAGE_CONNECTIONS meta-tool that prompts users to authenticate during chat. To turn it off and handle auth entirely in your own UI, set manage_connections to False:
- Python
- TypeScript
- API
Putting it together
A common pattern is to verify all required connections before starting the agent:- Python
- TypeScript
- API