userID you choose. Authentication is always per user. Each user connects their own accounts, their Gmail, their GitHub, their Slack, and Composio stores and refreshes those credentials against that userID.
This is the core idea: your agent runs the same tools for many people, and every tool call runs as a specific user against that user’s connected accounts. User A’s agent never touches user B’s data. You pass the userID when you create a session, and Composio handles the auth from there.
Because connections are stored under the userID, use a stable identifier, like your database ID, never one that can change.
userID best practices
userID best practices
- Recommended: database UUID or primary key (
user.id) - Acceptable: unique username (
user.username) - Avoid: email addresses (they can change)
- Never:
defaultin production (it exposes other users’ data)
How Composio handles authentication
Every session includes theCOMPOSIO_MANAGE_CONNECTIONS meta tool. When a tool needs an account, it reads the toolkit’s auth config (how that toolkit authenticates: method, scopes, credentials), creates a connection, and returns a secure Connect Link. This works for all Composio managed connections, so you don’t have to set up any OAuth credentials yourself.
The user signs in on the hosted link and Composio stores the resulting connected account. Credentials never pass through your app or the model, so it’s safe to surface the link right in the chat.
You only need a custom auth config to bring your own OAuth app, request specific scopes, or use a toolkit without managed auth.
In-chat authentication
The agent posts the Connect Link straight into the conversation. The user clicks it, signs in, and the agent retries the tool and continues. No auth UI for you to build. You can also callCOMPOSIO_MANAGE_CONNECTIONS yourself, intercept the Connect Link, and surface it wherever you need: DM it to the user, render it in your own UI, or email it. See redirect auth links for a worked example.
Custom callback URL
To send users back to your app after they connect, pass acallback_url:
- Python
- TypeScript
Manually triggering authentication
Don’t want to wait for the agent? Callsession.authorize() to generate a Connect Link on demand, for onboarding, a settings page, or a pre-flight check before a task.
Manual auth management
session.authorize(), callback URLs, connection status, and disabling in-chat promptsBehind the scenes
Composio manages authentication with auth configs. An auth config is a blueprint for how a toolkit authenticates across all your users. It defines three things:- Authentication method: OAuth2, Bearer token, API key, or Basic Auth
- Scopes: what actions your tools can perform
- Credentials: your own app credentials, or Composio’s managed auth
Connection lifecycle
For OAuth, Composio refreshes access tokens automatically before they expire, so connections stayACTIVE with no work from you. If a refresh token is revoked or expires, the connection moves to EXPIRED and the user has to reconnect.
Catch this before a tool call fails by subscribing to the composio.connected_account.expired event on a webhook subscription. When it fires, send the user a fresh Connect Link to re-authenticate:
- Python
- TypeScript