Connected Accounts And Auth

A new end user must connect their Google account. The agent initiates a managed OAuth connection request via Composio.

Initiate a connection request scoped to the user's entity_id; Composio returns a redirect URL. Send the user through that URL to complete the OAuth authorization-code flow. Do not attempt to collect the user's Google password or handle the token exchange yourself.

The user finishes the OAuth consent screen and is redirected back. The agent must confirm the connection is usable before executing actions.

After the redirect, poll/await the connected account until its status is ACTIVE before executing any action against it. Treat INITIATED as not-yet-usable. Only execute once the connection is confirmed active.

An integration uses an API key (not OAuth). The agent must establish an API-key connection for the user.

Initiate an API-key/bearer connection by collecting the credential over a secure channel and handing it to Composio's connection request so Composio stores it. Reference the resulting connection by id/entity for execution — do not keep the raw key in agent state or prompt.