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
Docs: New Authenticating tools page (#1850)
Sushmitha Mallesh8a912ed50c4d
diff --git a/fern/assets/images/executingtools.png b/fern/assets/images/executingtools.pngnew file mode 100644index 000000000..debfb441cBinary files /dev/null and b/fern/assets/images/executingtools.png differdiff --git a/fern/assets/images/integration-step-1-0.png b/fern/assets/images/integration-step-1-0.pngdeleted file mode 100644index a358a7b62..000000000Binary files a/fern/assets/images/integration-step-1-0.png and /dev/null differdiff --git a/fern/assets/images/integration-step-2-0.png b/fern/assets/images/integration-step-2-0.pngdeleted file mode 100644index 2e82be177..000000000Binary files a/fern/assets/images/integration-step-2-0.png and /dev/null differdiff --git a/fern/assets/images/integration-step-2-1.png b/fern/assets/images/integration-step-2-1.pngdeleted file mode 100644index 565e15e6b..000000000Binary files a/fern/assets/images/integration-step-2-1.png and /dev/null differdiff --git a/fern/pages/src/tool-calling/authenticating-tools.mdx b/fern/pages/src/tool-calling/authenticating-tools.mdxindex f17db52ac..ee762c6d0 100644--- a/fern/pages/src/tool-calling/authenticating-tools.mdx+++ b/fern/pages/src/tool-calling/authenticating-tools.mdx@@ -1,150 +1,282 @@---title: Authenticating Toolsimage: "https://og.composio.dev/api/og?title=Authenticating%20Tools" # image for socials-keywords: ''-subtitle: 'Learn how to authenticate tools'+keywords: '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.-Different apps (like Slack, Notion, Shopify) have their own authentication flows that users must complete to grant access to their accounts. Agents need authenticated access to these tools to perform actions on behalf of users.+An **Auth Config** is a *blueprint* that defines how authentication works for a toolkit across all your users. It defines:-## Creating an auth config--Each toolkit comes with its own _auth config_.-This configuration is used to authenticate the users to the tools.+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*-The first step is to create an auth config for any toolkit that you want to use.+<Frame>+ <img src="../../../assets/images/executingtools.png" alt="Composio introduction image" />+</Frame>-<Note title="Auth configs are reusable">-The appropriate developer credentials and app level configurations like scopes, API endpoints, etc. are scoped to an auth config.+## Creating an auth config-Once created, it's reusable across multiple users.+### Using the Dashboard:-</Note>--The dashboard offers a guided process for all app types.<Steps>- <Step title="Select App">- Navigate to the [Apps page](https://app.composio.dev/apps) and choose the app you want to integrate (for example, Google Sheets).- <Frame background="subtle" title="Application Selection Screen">- <img src="../../../assets/images/integration-step-1-0.png" />- </Frame>+ <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**).+ </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.</Step>- <Step title="Initiate Setup">- Click the **"Setup Integration"** button.- <Frame background="subtle" title="Auth Config Setup Interface">- <img src="../../../assets/images/integration-step-2-0.png" />- </Frame>+ <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.+ - **API Key/Bearer Token**: Permissions are typically fixed based on the key's access level.</Step>- <Step title="Configure Auth Config Settings">- Select among the supported auth schemes of OAuth2, API Key, Bearer Token, Basic Auth, depending on the toolkit.- Switch between the auth schemes and configure the scopes, developer credentials, etc here.-- <Note title="Composio Managed Auth" icon="info">- You may also choose to use Composio's managed auth for certain toolkits or use your own auth credentials.- It is recommended to specify your own credentials for production workloads and ability to control scopes, etc.- </Note>-- <Frame background="subtle" title="Auth Config Settings">- <img src="../../../assets/images/auth-config-creation.png" />- </Frame>+ <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.</Step>- <Step title="Create and Get auth config ID">- Click **"Create Integration"**. After creation, **copy the displayed ID starting with `ac_`**. This is your auth config ID. This is _not_ a sensitive ID -- you can save it in environment variables or a database.- **This ID will be used to create connections to the toolkit for a given user.**+ <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*.</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.+</Note>++**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+<Card title="Programmatic creation" href="/docs/programmatic-auth-configs" icon="fa-solid fa-code">- In case of dealing with multiple toolkits across different projects, you can create auth configs- programmatically.+ For managing auth configs across multiple projects, you can create them programmatically via the API</Card>-## Connecting to an OAuth toolkit-Here's how to authenticate a toolkit for a given user using the OAuth flow.+## Connecting an account:++With an auth config created, you're ready to authenticate your users!++**Choose the section below that matches your toolkit's authentication method:**+### OAuth Connections++**OAuth** connections redirect users to the toolkit's login page. Popular toolkits that use **OAuth** authentication include: *Gmail*, *Notion* etc.++Here's how to initiate the flow:+<CodeGroup>-<SnippetCode- src="fern/snippets/tool-calling/python/auth-tools.py"- startLine={1}- endLine={21}- title="Python"-/>-<SnippetCode- src="fern/snippets/tool-calling/typescript/auth-tools.ts"- startLine={1}- endLine={21}- title="TypeScript"-/>+```python Python {11-15}+from composio import Composio++composio = Composio(api_key="YOUR_COMPOSIO_API_KEY")++# Use the "AUTH CONFIG ID" from your dashboard+auth_config_id = "ac_UdqFwixfy3cV"++# Use a unique identifier for each user in your application+user_id = "user_123"++connection_request = composio.connected_accounts.initiate(+ user_id=user_id,+ auth_config_id=auth_config_id,+ config={"auth_scheme": "OAUTH2"}+)++# Redirect user to this URL+print(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)+# Recommended when the connection_request object is no longer available++print(f"Connection established: {connected_account.id}")+```+++```typescript {10-13}+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';+// Use a unique identifier for each user in your application+const userId = 'user_4567';++const connRequest = await composio.connectedAccounts.initiate(+ userId,+ authConfigId+);++console.log(`Redirect URL: ${connRequest.redirectUrl}`);++const connectedAccount = await connRequest.waitForConnection();++// Alternative: if you only have the connection request ID+// const connectedAccount = await composio.connectedAccounts+// .waitForConnection(connRequest.id);+// Recommended when the connRequest object is no longer available++console.log(`Connection established: ${connectedAccount.id}`);+```</CodeGroup>-## Connecting to an API Key toolkit-For API key based toolkits, you can either request the user to provide the API key or provide your own!-### Creating the connection+### Redirecting Users (OAuth only)-If you know the required authentication fields for your toolkit (like `apiKey` for most API-based services), you can directly create the connection:+For OAuth flows, you can control where users are redirected after authentication by providing a callback Url:<CodeGroup>-<SnippetCode- src="fern/snippets/tool-calling/python/auth-tools.py"- startLine={23}- endLine={34}- title="Python"-/>-<SnippetCode- src="fern/snippets/tool-calling/typescript/auth-tools.ts"- startLine={24}- endLine={37}- title="TypeScript"-/>+```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>-## Specifying auth schemes-Composio supports a wide range of auth schemes; OAuth2, API Key, HTTP Basic and many more.-Each app (and toolkit) has different connection options required for each auth scheme. For example;-- Shopify requires an *API key* from each user for the API Key auth scheme.-- Airtable requires the Bearer token from each user for the *Bearer* auth scheme.-The auth scheme information is typed and can be configured as follows:+### 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:<CodeGroup>-<SnippetCode- src="fern/snippets/tool-calling/python/auth-tools.py"- startLine={35}- endLine={46}- title="Python"-/>-<SnippetCode- src="fern/snippets/tool-calling/typescript/auth-tools.ts"- startLine={38}- endLine={50}- title="TypeScript"-/>+```python {13-19}+from composio import Composio++composio = 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+user_id = "user_12323"+# API key provided by the user (collected from your app's UI)+# or use your own key+user_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}+ }+)++print(f"Connection established: {connection_request.id}")+```++```typescript {12-18}+import { Composio, AuthScheme } from '@composio/core';++const composio = new Composio({apiKey: "your_api_key"});++// Use the "AUTH CONFIG ID" from your dashboard+const authConfigId = 'ac_ZUWpt850AqTN';+// Use a unique identifier for each user in your application+const 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,+ }),+});++console.log(`Connection established: ${connectionRequest.id}`);+```</CodeGroup>-It might be useful to read all the optional and required auth config fields for a toolkit and optionally prompt the user for the values.+## Fetching the required `config` parameters for an Auth Config-## Redirecting users+When working with any toolkits, you can **inspect an auth config** to understand its *authentication requirements* and *expected parameters*.-To control where the users are redirected after they have authenticated, you can use the `redirectUrl` parameter in the `initiate` method.-In this case, the user will be redirected to `https://www.yourapp.com/callback` after they have authenticated.+Here is how you would fetch the authentication method and input fields:<CodeGroup>-<SnippetCode- src="fern/snippets/tool-calling/python/callback-url.py"- startLine={10}- endLine={20}- title="Python"-/>-<SnippetCode- src="fern/snippets/tool-calling/typescript/callback-url.ts"- startLine={10}- endLine={20}- title="TypeScript"-/>+```python {9}+from composio import Composio++composio = Composio(api_key="your_api_key")++# Use the "AUTH CONFIG ID" from your dashboard+auth_config_id = "ac_ZUWpt850AqTN"++# Fetch the auth configuration details+auth_config = composio.auth_configs.get(auth_config_id)++# Check what authentication method this config uses+print(f"Authentication method: {auth_config.auth_scheme}")++# See what input fields are required+print(f"Required fields: {auth_config.expected_input_fields}")+```++```typescript {9}+import { Composio } from '@composio/core';++const composio = new Composio({apiKey: "your_api_key"});++// Use the "AUTH CONFIG ID" from your dashboard+const authConfigId = 'ac_ZUWpt850AqTN';++// Fetch the auth configuration details+const authConfig = await composio.authConfigs.get(authConfigId);++console.log(`Authentication method: ${authConfig.authScheme}`);+console.log(`Required fields:`, authConfig.expectedInputFields);+```</CodeGroup>+++## 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.++<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.+</Note>++## Next Step+With authentication set up, you can now fetch and execute tools. See [Executing Tools](/docs/executing-tools) to get started.diff --git a/fern/snippets/tool-calling/python/auth-tools.py b/fern/snippets/tool-calling/python/auth-tools.pydeleted file mode 100644index b1841020a..000000000--- a/fern/snippets/tool-calling/python/auth-tools.py+++ /dev/null@@ -1,46 +0,0 @@-from composio import Composio-from composio.types import auth_scheme--linear_auth_config_id = "ac_dqYN9oElNVlg"-user_id = "0000-1111-2222"-composio = Composio()--# Create a new connected account-connection_request = composio.connected_accounts.initiate(- user_id=user_id, auth_config_id=linear_auth_config_id, config={"auth_scheme": "OAUTH2"}-)-print(connection_request.redirect_url)--# Wait for the connection to be established-connected_account = connection_request.wait_for_connection()--# If you only have the connection request ID, you can also wait using:--connected_account = composio.connected_accounts.wait_for_connection(connection_request.id)-# Recommended for when connection_request object is destroyed--# API key based toolkit-# from composio.types import auth_scheme-serp_auth_config_id = "ac_VWmFEC55Zgv6"--# Retrieved from the user-user_api_key = "sk_1234567890"--connection_request = composio.connected_accounts.initiate(- user_id=user_id,- auth_config_id=serp_auth_config_id,- config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}},-)--# Auth scheme config for Airtable Bearer-# from composio.types import auth_scheme-airtable_auth_config_id = "ac_1234567"--# Retrieved from user-user_bearer_token = "1234567890"--airtable_connection_req = composio.connected_accounts.initiate(- user_id=user_id,- auth_config_id=airtable_auth_config_id,- config={"auth_scheme": "BEARER_TOKEN", "val": user_bearer_token},-)