Skip to main content
Manual authentication lets you connect users to toolkits outside the chat flow. Reach for it when you want to:
  • Pre-authenticate users before they start chatting.
  • Build a custom connections UI in your app.

Authorize a toolkit

Call session.authorize() to generate a Connect Link URL, redirect the user, and wait for them to finish:
Redirect the user to the 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, call session.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 a callbackUrl 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.
After authentication, Composio redirects the user to your callback URL with the following parameters appended, while preserving your existing ones:

Identify the connected account

After authentication, use the account returned by wait_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:
Toolkit metadata describes where to request a profile; it doesn’t contain the account owner’s details. Endpoint availability, required scopes, and response fields vary by provider. If the metadata is absent, use a documented profile endpoint or tool for that provider. A GitHub username or display label isn’t a verified email address. For an application policy, validate the provider’s response before giving an agent access to the account. Follow Restrict Gmail connections to an email domain for a complete example that checks the mailbox address and disables rejected connections. Return only the fields your UI needs, not the account’s authentication state.

Check connection status

Use session.toolkits() to see all toolkits in the session and their connection status:

Disabling in-chat auth

By default, sessions include the COMPOSIO_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:

Putting it together

A common pattern is to verify all required connections before starting the agent:

Next

Managing multiple connected accounts