Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
Update docs with the new Connect Link feature (#1928)
Sushmitha Mallesh95cff2049264
diff --git a/fern/pages/src/tool-calling/authenticating-tools.mdx b/fern/pages/src/tool-calling/authenticating-tools.mdxindex a62557239..3c27ccb70 100644--- a/fern/pages/src/tool-calling/authenticating-tools.mdx+++ b/fern/pages/src/tool-calling/authenticating-tools.mdx@@ -1,17 +1,18 @@---title: Authenticating Tools-image: "https://og.composio.dev/api/og?title=Authenticating%20Tools" # image for socials+image: 'https://og.composio.dev/api/og?title=Authenticating%20Tools' # image for socialskeywords: 'auth config, authentication, oauth, api key, user authentication'subtitle: 'Create auth configs and connect user accounts'hide-nav-links: false----The first step in authenticating your Users is to create an **Auth Config**. Every toolkit has its own *authentication method* such as **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:+The first step in authenticating your Users is to create an **Auth Config**. Every toolkit has its own _authentication method_ such as **OAuth**, **API key**, **Basic Auth**, or custom schemes.-1. **Authentication method** - *OAuth2*, *Bearer token*, *API key*, or *Basic Auth*-2. **Scopes** - *what actions your tools can perform*-3. **Credentials** - *whether you'll use your own app credentials or Composio's managed auth*+An **Auth Config** is a _blueprint_ that defines how authentication works for a toolkit across all your users. It defines:++1. **Authentication method** - _OAuth2_, _Bearer token_, _API key_, or _Basic Auth_+2. **Scopes** - _what actions your tools can perform_+3. **Credentials** - _whether you'll use your own app credentials or Composio's managed auth_<Frame><img src="../../../assets/images/executingtools.png" alt="Composio introduction image" />@@ -19,36 +20,39 @@ An **Auth Config** is a *blueprint* that defines how authentication works for a## Creating an auth config-### Using the Dashboard:+### Using the Dashboard<Steps><Step title="**Selecting a toolkit**">- Navigate to <a target="_blank" href="https://platform.composio.dev?next_page=%2Fauth-configs" target="_blank">Auth Configs</a> tab in your dashboard and click "**Create Auth Config**". Find and select the toolkit you want to integrate (e.g., **Gmail**, **Slack**, **GitHub**).+ Navigate to <a target="_blank"href="https://platform.composio.dev?next_page=%2Fauth-configs"target="_blank">Auth Configs</a> tab in your dashboard and click "**Create Auth Config**". Find and select the toolkit you want to integrate (e.g., **Gmail**, **Slack**, **GitHub**).</Step><Step title="**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.+ Each toolkit supports different authentication methods such as **OAuth**, **API Key**, **Bearer+ Token**. Select from the available options for your toolkit.</Step><Step title="**Configure scopes**">- Depending on your authentication method, you may need to configure scopes:- - **OAuth2**: Configure scopes for what data and actions your integration can access.+ Depending on your authentication method, you may need to configure scopes:+ - **OAuth2**: Configure scopes for what data and actions your integration can access.- **API Key/Bearer Token**: Permissions are typically fixed based on the key's access level.</Step><Step title="**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-- **For custom authentication schemes:**- You must provide your own credentials regardless of environment.+ **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++ **For custom authentication schemes:**++ You must provide your own credentials regardless of environment.</Step><Step title="**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*.+ 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](#connecting-an-account).</Step></Steps><Note title="Auth configs are reusable">- Auth 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.+ Auth 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.</Note>**When to create multiple auth configs?**@@ -56,74 +60,127 @@ An **Auth Config** is a *blueprint* that defines how authentication works for aYou 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 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<Card title="Programmatic creation" href="/docs/programmatic-auth-configs" icon="fa-solid fa-code">- For managing auth configs across multiple projects, you can create them programmatically via the API+ For managing auth configs across multiple projects, you can create them programmatically via the+ API</Card>+## Connecting an account-## Connecting an account:+With an auth config created, you're ready to authenticate your users!-With an auth config created, you're ready to authenticate your users!+You can either use [**Connect Link**](#hosted-authentication-connect-link) for a hosted authentication flow, or use [**Direct SDK Integration**](#direct-sdk-integration).-**Choose the section below that matches your toolkit's authentication method:**-### OAuth Connections+### 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.++<CodeGroup>+```python Python {11-13}+from composio import Composio++composio = Composio(api_key="your_api_key")++# Use the "AUTH CONFIG ID" from your dashboard+auth_config_id = "your_auth_config_id"++# Use a unique identifier for each user in your application+user_id = 'user-1349-129-12'++connection_request = composio.connected_accounts.link(user_id, auth_config_id, {+ 'callback_url': 'https://your-app.com/callback'+})+redirect_url = connection_request.redirect_url+print(f"Visit: {redirect_url} to authenticate your account")++# Wait for the connection to be established+connected_account = connection_request.wait_for_connection()+print(connected_account.id)+```+```typescript Typescript {11-13}+import { Composio } from '@composio/core';++const composio = new Composio({apiKey: "your_api_key"});++// Use the "AUTH CONFIG ID" from your dashboard+const authConfigId = 'your_auth_config_id';-**OAuth** connections redirect users to the toolkit's login page. Popular toolkits that use **OAuth** authentication include: *Gmail*, *Notion* etc.+// Use a unique identifier for each user in your application+const userId = 'user-1349-129-12';++const connectionRequest = await composio.connectedAccounts.link(userId, authConfigId, {+ callbackUrl: 'https://your-app.com/callback'+});+const redirectUrl = connectionRequest.redirectUrl;+console.log(`Visit: ${redirectUrl} to authenticate your account`);++// Wait for the connection to be established+const connectedAccount = await composio.connectedAccounts.waitForConnection(connectionRequest.id);+console.log(connectedAccount.id)++````++</CodeGroup>++### Direct SDK Integration++**Choose the section below that matches your toolkit's authentication method:**-Here's how to initiate the flow:+#### 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:<CodeGroup>-```python Python {11-15}+```python Python {11-16}from composio import Composiocomposio = Composio(api_key="YOUR_COMPOSIO_API_KEY")# Use the "AUTH CONFIG ID" from your dashboard-auth_config_id = "ac_UdqFwixfy3cV"+auth_config_id = "your_auth_config_id"# Use a unique identifier for each user in your application-user_id = "user_123"+user_id = "user-1349-129-12"connection_request = composio.connected_accounts.initiate(- user_id=user_id,- auth_config_id=auth_config_id,- config={"auth_scheme": "OAUTH2"}+ user_id=user_id,+ auth_config_id=auth_config_id,+ config={"auth_scheme": "OAUTH2"},+ callback_url="https://www.yourapp.com/callback")--# Redirect user to this URLprint(f"Redirect URL: {connection_request.redirect_url}")connected_account = connection_request.wait_for_connection()# Alternative: if you only have the connection request ID# connected_account = composio.connected_accounts.wait_for_connection(-# connection_request.id)+# connection_request.id)# Recommended when the connection_request object is no longer availableprint(f"Connection established: {connected_account.id}")-```+````-```typescript {10-13}+```typescript {10-14}import { Composio } from '@composio/core';const composio = new Composio({apiKey: "YOUR_COMPOSIO_API_KEY"});// Use the "AUTH CONFIG ID" from your dashboard-const authConfigId = 'ac_UdqFwixfy3cV';+const authConfigId = 'your_auth_config_id';// Use a unique identifier for each user in your applicationconst userId = 'user_4567';const connRequest = await composio.connectedAccounts.initiate(- userId,- authConfigId+ userId,+ authConfigId,+ callbackUrl: 'https://www.yourapp.com/callback');-console.log(`Redirect URL: ${connRequest.redirectUrl}`);const connectedAccount = await connRequest.waitForConnection();@@ -134,38 +191,11 @@ const connectedAccount = await connRequest.waitForConnection();// Recommended when the connRequest object is no longer availableconsole.log(`Connection established: ${connectedAccount.id}`);-```-</CodeGroup>--+````-### Redirecting Users (OAuth only)--For OAuth flows, you can control where users are redirected after authentication by providing a callback Url:--<CodeGroup>-```python {5}-connection_request = composio.connected_accounts.initiate(- user_id=user_id,- auth_config_id=auth_config_id,- config={"auth_scheme": "OAUTH2"},- callback_url="https://www.yourapp.com/callback"-)-```--```typescript {5}-const connRequest = await composio.connectedAccounts.initiate(- userId,- authConfigId,- {- callbackUrl: 'https://www.yourapp.com/callback',- }-);-```</CodeGroup>--### Services with Additional Parameters+#### Services with Additional ParametersSome services like Zendesk require additional parameters such as `subdomain`:@@ -173,86 +203,84 @@ Some services like Zendesk require additional parameters such as `subdomain`:```python# For Zendesk - include subdomainconnection_request = composio.connected_accounts.initiate(- user_id=user_id,- auth_config_id=auth_config_id,- config=auth_scheme.oauth2(subdomain="mycompany") # For mycompany.zendesk.com+ user_id=user_id,+ auth_config_id=auth_config_id,+ config=auth_scheme.oauth2(subdomain="mycompany") # For mycompany.zendesk.com)``````typescriptimport { AuthScheme } from '@composio/core';-// For Zendesk - include subdomain-const connRequest = await composio.connectedAccounts.initiate(- userId,- authConfigId,- {- config: AuthScheme.OAuth2({- subdomain: 'mycompany'- })- }-);+// For Zendesk - include subdomain+const connRequest = await composio.connectedAccounts.initiate(userId, authConfigId, {+ config: AuthScheme.OAuth2({+ subdomain: 'mycompany',+ }),+});```+</CodeGroup>-### API Key Connections+#### 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.+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:<CodeGroup>-```python {13-19}+```python {16-22}from composio import Composiocomposio = Composio(api_key="your_api_key")# Use the "AUTH CONFIG ID" from your dashboard-auth_config_id = "ac_ZUWpt850AqTN"-# Use a unique identifier for each user in your application+auth_config_id = "your_auth_config_id"++# Use a unique identifier for each user in your applicationuser_id = "user_12323"+# API key provided by the user (collected from your app's UI)# or use your own keyuser_api_key = "user_api_key_here"connection_request = composio.connected_accounts.initiate(- user_id=user_id,- auth_config_id=auth_config_id,- config={- "auth_scheme": "API_KEY", "val": {"api_key": user_api_key}- }+ user_id=user_id,+ auth_config_id=auth_config_id,+ config={+ "auth_scheme": "API_KEY", "val": {"api_key": user_api_key}+ })print(f"Connection established: {connection_request.id}")-```-```typescript {12-18}+````++```typescript {12-16}import { Composio, AuthScheme } from '@composio/core';-const composio = new Composio({apiKey: "your_api_key"});+const composio = new Composio({ apiKey: 'your_api_key' });// Use the "AUTH CONFIG ID" from your dashboard-const authConfigId = 'ac_ZUWpt850AqTN';+const authConfigId = 'your_auth_config_id';// Use a unique identifier for each user in your applicationconst userId = 'user12345678';// API key provided by the user (collected from your app's UI)const userApiKey = 'user_api_key_here';-const connectionRequest = await composio.connectedAccounts.initiate(- userId, authConfigId,- {- config: AuthScheme.APIKey({- api_key: userApiKey,- }),+const connectionRequest = await composio.connectedAccounts.initiate(userId, authConfigId, {+ config: AuthScheme.APIKey({+ api_key: userApiKey,+ }),});console.log(`Connection established: ${connectionRequest.id}`);-```-</CodeGroup>+````+</CodeGroup>## Fetching the required `config` parameters for an Auth Config-When working with any toolkits, you can **inspect an auth config** to understand its *authentication requirements* and *expected parameters*.+When working with any toolkits, 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:@@ -263,7 +291,7 @@ from composio import Composiocomposio = Composio(api_key="your_api_key")# Use the "AUTH CONFIG ID" from your dashboard-auth_config_id = "ac_ZUWpt850AqTN"+auth_config_id = "your_auth_config_id"# Fetch the auth configuration detailsauth_config = composio.auth_configs.get(auth_config_id)@@ -273,24 +301,25 @@ print(f"Authentication method: {auth_config.auth_scheme}")# See what input fields are requiredprint(f"Required fields: {auth_config.expected_input_fields}")-```++```````typescript {9}import { Composio } from '@composio/core';-const composio = new Composio({apiKey: "your_api_key"});+const composio = new Composio({ apiKey: 'your_api_key' });// Use the "AUTH CONFIG ID" from your dashboard-const authConfigId = 'ac_ZUWpt850AqTN';+const authConfigId = 'your_auth_config_id';// Fetch the auth configuration detailsconst authConfig = await composio.authConfigs.get(authConfigId);console.log(`Authentication method: ${authConfig.authScheme}`);console.log(`Required fields:`, authConfig.expectedInputFields);-```-</CodeGroup>+````+</CodeGroup>## Other Authentication Methods@@ -303,9 +332,12 @@ Composio also supports a wide range of other auth schemas:**Custom Schemes** - Some toolkits use their own custom authentication methods. Follow the toolkit-specific requirements for such cases.<Note title="Fetching auth config">-For any of these methods, [fetch the config parameter](#fetching-the-required-config-parameters-for-an-auth-config) to determine the exact fields required.-Every toolkit has its own requirements, and understanding these is essential for successfully creating connections.+ For any of these methods, [fetch the config+ parameter](#fetching-the-required-config-parameters-for-an-auth-config) to determine the exact+ fields required. Every toolkit has its own requirements, and understanding these is essential for+ successfully creating connections.</Note>## Next Step+With authentication set up, you can now fetch and execute tools. See [Executing Tools](/docs/executing-tools) to get started.