Legacy API: prefer sessionsThis guide covers legacy direct-authentication methods, which remain supported for existing integrations. For new integrations, use sessions with in-chat authentication or manual authentication. If you use direct authentication today, consider migrating to sessions.
OAuth, API key, Basic Auth, or custom schemes.
An Auth Config is a blueprint that defines how authentication works for a toolkit across all your users. It defines:
- Authentication method -
OAuth2,Bearer token,API key, orBasic Auth - Scopes - what actions your tools can perform
- Credentials - whether you’ll use your own app credentials or Composio’s managed auth
Connecting accounts with managed OAuthFor Composio-managed OAuth, use
connectedAccounts.link() in TypeScript or connected_accounts.link() in Python. Follow Hosted Authentication below. initiate() remains available for custom OAuth configs and non-OAuth schemes. See the migration guide.Creating an auth config
Using the Dashboard
1
Selecting a toolkit
Navigate to Auth Configs tab in your dashboard and click “Create Auth Config”. Find and select the toolkit you want to integrate (e.g., Gmail, Slack, GitHub).
2
Selecting the Authentication method
Each toolkit supports different authentication methods such as OAuth, API Key, Bearer Token. Select from the available options for your toolkit.
3
Configure scopes
Depending on your authentication method, you may need to configure scopes:
- OAuth2: Configure scopes for what data and actions your app can access.
- API Key/Bearer Token: Permissions are typically fixed based on the key’s access level.
4
Authentication Management
For OAuth toolkits:
- Development/Testing: Use Composio’s managed authentication (no setup required)
- Production: Generate your own OAuth credentials from the toolkit’s developer portal
Want to remove Composio branding from OAuth screens? See White-labeling for details.
5
You are all set!
Click “Create Auth Configuration” button and you have completed your first step! Now you can move ahead to authenticating your users by Connecting an Account.
Auth configs are reusableAuth configs contain your developer credentials and app-level settings (scopes, authentication method, etc.). Once created, you can reuse the same auth config for all your users.
When to create multiple auth configs?
You should create multiple auth configs for the same toolkit when you need:- Different authentication methods - One OAuth config and one API key config
- Different scopes - Separate configs for read-only vs full access
- Different OAuth apps - Using separate client credentials for different environments
- Different permission levels - Limiting actions for specific use cases
Programmatic creation
For managing auth configs across multiple projects, you can create them programmatically via the API
Production white-labeling
Remove Composio branding from OAuth screens for a fully white-labeled authentication experience
Connecting an account
With an auth config created, you’re ready to authenticate your users! You can either use Connect Link for a hosted authentication flow, or use Direct SDK Setup.User authentication requires a userID - a unique identifier that groups connected accounts together. Learn more about User scoping to understand how to structure userIDs for your application.
Hosted Authentication (Connect Link)
Redirect users to a Composio-hosted URL that handles the entire authentication process—OAuth flows, API key collection, or custom fields like subdomain. You can specify a callback URL to control where users return after authentication.
Connect Link authentication screen
- Python
- TypeScript
- API
link() refuses to create a second active connection for the same user and auth config. If your user intentionally needs another account on that auth config, pass allow_multiple=True in Python or allowMultiple: true in TypeScript. Enable multi-account mode when a session needs to use those accounts together.
Customizing Connect Link
You can customize the Connect Link with your logo and app title, or fully white-label OAuth consent screens with your own developer apps.White-labeling
Redirecting users after authentication
You can include custom query parameters in your callback URL to carry context through the auth flow, such as identifying which user or session triggered the connection. Composio preserves your parameters and appends its own after authentication completes.
For example, if your callback URL is
https://your-app.com/callback?user_id=user_123, the redirect after successful auth will be:
Direct SDK Setup
Choose the section below that matches your toolkit’s authentication method:OAuth Connections
For OAuth flows, you’ll redirect users to complete authorization. You can specify a callback URL to control where users return after authentication:- Python
- TypeScript
- API
When using callback URLs with
initiate(), the appended query parameters use camelCase (connectedAccountId, appName) instead of snake_case. See Redirecting users after authentication.Services with Additional Parameters
Some services like Zendesk require additional parameters such assubdomain:
- Python
- TypeScript
- API
API Key Connections
For API key authentication, you can either collect API keys from each user or use your own API key for all users. Popular toolkits that use API keys include Stripe, Perplexity, etc. Here is how to initiate the flow:- Python
- TypeScript
- API
Fetching the required config parameters for an Auth Config
When working with any toolkit, you can inspect an auth config to understand its authentication requirements and expected parameters. Here is how you would fetch the authentication method and input fields:- Python
- TypeScript
- API
Other Authentication Methods
Composio also supports a wide range of other auth schemas: Bearer Token - Similar to API keys, provide the user’s bearer token directly when creating the connection. Basic Auth - Provide username and password credentials for services that use HTTP Basic Authentication. Custom Schemes - Some toolkits use their own custom authentication methods. Follow the toolkit-specific requirements for such cases.Fetching auth configFor any of these methods, fetch the config parameter to determine the exact fields required. Every toolkit has its own requirements, and understanding these is essential for successfully creating connections.
Connection Statuses
After creating a connection, it will have one of the following statuses that indicates its current state:Why connections expire
Composio automatically refreshes OAuth tokens before they expire. A connection is only marked as EXPIRED after refresh attempts have failed. Common reasons:- User revoked access — The user went to the provider’s settings (e.g., Google Account > Security > Third-party apps) and removed your app’s access.
- OAuth app deleted or disabled — The OAuth application credentials were deleted or disabled in the provider’s developer console.
- Refresh token expired — Some providers (e.g., Google with test/unverified apps) expire refresh tokens after a set period. Once expired, a new OAuth consent flow is required.
- Provider-side revocation — The provider revoked tokens due to policy changes, security events, or account-level restrictions.
- Repeated transient failures — If token refresh fails multiple times consecutively (e.g., due to prolonged provider outages), Composio marks the connection as expired after a threshold of failures.
status_reason field on the connected account for the specific reason. You can also subscribe to connection expiry events to detect this proactively.
Waiting for Connection Establishment
ThewaitForConnection method allows you to poll for a connection to become active after initiating authentication. This is useful when you need to ensure a connection is ready before proceeding.
- Python
- TypeScript
- API
- Becomes ACTIVE (returns the connected account)
- Enters a terminal state like FAILED or EXPIRED (throws an error)
- Exceeds the specified timeout (throws a timeout error)
Checking Connection Status
You can check the status of a connected account programmatically:- Python
- TypeScript
- API
Only connections with ACTIVE status can be used to execute tools. If a connection is in any other state, you’ll need to take appropriate action (re-authenticate, wait for processing, etc.) before using it.