@devries-cameron20 / composio Mirror · read-only / commits / 8a912ed50
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 20:45 UTC

Docs: New Authenticating tools page (#1850)

Sushmitha Mallesh committed Aug 17, 2025 at 12:25 UTC 8a912ed50c4d5495a9511755f20ce9337e6aee10
6 files changed +237 -151
fern/assets/images/executingtools.png
Binary files /dev/null and b/fern/assets/images/executingtools.png differ
fern/assets/images/integration-step-1-0.png
Binary files a/fern/assets/images/integration-step-1-0.png and /dev/null differ
fern/assets/images/integration-step-2-0.png
Binary files a/fern/assets/images/integration-step-2-0.png and /dev/null differ
fern/assets/images/integration-step-2-1.png
Binary files a/fern/assets/images/integration-step-2-1.png and /dev/null differ
fern/pages/src/tool-calling/authenticating-tools.mdx
+237 -105
@@ -1,150 +1,282 @@
1 ---
2 title: Authenticating Tools
3 image: "https://og.composio.dev/api/og?title=Authenticating%20Tools" # image for socials
4 -keywords: ''
5 -subtitle: 'Learn how to authenticate tools'
4 +keywords: 'auth config, authentication, oauth, api key, user authentication'
5 +subtitle: 'Create auth configs and connect user accounts'
6 hide-nav-links: false
7 ---
8 +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.
9
9 -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.
10 +An **Auth Config** is a *blueprint* that defines how authentication works for a toolkit across all your users. It defines:
11
11 -## Creating an auth config
12 -
13 -Each toolkit comes with its own _auth config_.
14 -This configuration is used to authenticate the users to the tools.
12 +1. **Authentication method** - *OAuth2*, *Bearer token*, *API key*, or *Basic Auth*
13 +2. **Scopes** - *what actions your tools can perform*
14 +3. **Credentials** - *whether you'll use your own app credentials or Composio's managed auth*
15
16 -The first step is to create an auth config for any toolkit that you want to use.
16 +<Frame>
17 + <img src="../../../assets/images/executingtools.png" alt="Composio introduction image" />
18 +</Frame>
19
18 -<Note title="Auth configs are reusable">
19 -The appropriate developer credentials and app level configurations like scopes, API endpoints, etc. are scoped to an auth config.
20 +## Creating an auth config
21
21 -Once created, it's reusable across multiple users.
22 +### Using the Dashboard:
23
23 -</Note>
24 -
25 -The dashboard offers a guided process for all app types.
24 <Steps>
27 - <Step title="Select App">
28 - Navigate to the [Apps page](https://app.composio.dev/apps) and choose the app you want to integrate (for example, Google Sheets).
29 - <Frame background="subtle" title="Application Selection Screen">
30 - <img src="../../../assets/images/integration-step-1-0.png" />
31 - </Frame>
25 + <Step title="**Selecting a toolkit**">
26 + 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**).
27 + </Step>
28 + <Step title="**Selecting the Authentication method**">
29 + Each toolkit supports different authentication methods such as **OAuth**, **API Key**, **Bearer Token**. Select from the available options for your toolkit.
30 </Step>
33 - <Step title="Initiate Setup">
34 - Click the **"Setup Integration"** button.
35 - <Frame background="subtle" title="Auth Config Setup Interface">
36 - <img src="../../../assets/images/integration-step-2-0.png" />
37 - </Frame>
31 + <Step title="**Configure scopes**">
32 + Depending on your authentication method, you may need to configure scopes:
33 + - **OAuth2**: Configure scopes for what data and actions your integration can access.
34 + - **API Key/Bearer Token**: Permissions are typically fixed based on the key's access level.
35 </Step>
39 - <Step title="Configure Auth Config Settings">
40 - Select among the supported auth schemes of OAuth2, API Key, Bearer Token, Basic Auth, depending on the toolkit.
41 - Switch between the auth schemes and configure the scopes, developer credentials, etc here.
42 -
43 - <Note title="Composio Managed Auth" icon="info">
44 - You may also choose to use Composio's managed auth for certain toolkits or use your own auth credentials.
45 - It is recommended to specify your own credentials for production workloads and ability to control scopes, etc.
46 - </Note>
47 -
48 - <Frame background="subtle" title="Auth Config Settings">
49 - <img src="../../../assets/images/auth-config-creation.png" />
50 - </Frame>
36 + <Step title="**Authentication Management**">
37 + **For OAuth toolkits:**
38 + - **Development/Testing**: Use Composio's managed authentication (no setup required)
39 + - **Production**: Generate your own OAuth credentials from the toolkit's developer portal
40 +
41 + **For custom authentication schemes:**
42 + You must provide your own credentials regardless of environment.
43 </Step>
52 - <Step title="Create and Get auth config ID">
53 - 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.
54 - **This ID will be used to create connections to the toolkit for a given user.**
44 + <Step title="**You are all set!**">
45 + Click "**Create Auth Configuration**" button and you have completed your first step!
46 + Now you can move ahead to authenticating your users by *Connecting an Account*.
47 </Step>
48 </Steps>
49
50 +<Note title="Auth configs are reusable">
51 + 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.
52 +</Note>
53 +
54 +**When to create multiple auth configs?**
55 +
56 +You should create multiple auth configs for the same toolkit when you need:
57 +
58 +- **Different authentication methods** - One OAuth config and one API key config
59 +- **Different scopes** - Separate configs for read-only vs full access
60 +- **Different OAuth apps** - Using separate client credentials for different environments
61 +- **Different permission levels** - Limiting actions for specific use cases
62 +
63 <Card title="Programmatic creation" href="/docs/programmatic-auth-configs" icon="fa-solid fa-code">
59 - In case of dealing with multiple toolkits across different projects, you can create auth configs
60 - programmatically.
64 + For managing auth configs across multiple projects, you can create them programmatically via the API
65 </Card>
66
63 -## Connecting to an OAuth toolkit
67
65 -Here's how to authenticate a toolkit for a given user using the OAuth flow.
68 +## Connecting an account:
69 +
70 +With an auth config created, you're ready to authenticate your users!
71 +
72 +**Choose the section below that matches your toolkit's authentication method:**
73 +### OAuth Connections
74 +
75 +**OAuth** connections redirect users to the toolkit's login page. Popular toolkits that use **OAuth** authentication include: *Gmail*, *Notion* etc.
76 +
77 +Here's how to initiate the flow:
78 +
79
80 <CodeGroup>
68 -<SnippetCode
69 - src="fern/snippets/tool-calling/python/auth-tools.py"
70 - startLine={1}
71 - endLine={21}
72 - title="Python"
73 -/>
74 -<SnippetCode
75 - src="fern/snippets/tool-calling/typescript/auth-tools.ts"
76 - startLine={1}
77 - endLine={21}
78 - title="TypeScript"
79 -/>
81 +```python Python {11-15}
82 +from composio import Composio
83 +
84 +composio = Composio(api_key="YOUR_COMPOSIO_API_KEY")
85 +
86 +# Use the "AUTH CONFIG ID" from your dashboard
87 +auth_config_id = "ac_UdqFwixfy3cV"
88 +
89 +# Use a unique identifier for each user in your application
90 +user_id = "user_123"
91 +
92 +connection_request = composio.connected_accounts.initiate(
93 + user_id=user_id,
94 + auth_config_id=auth_config_id,
95 + config={"auth_scheme": "OAUTH2"}
96 +)
97 +
98 +# Redirect user to this URL
99 +print(f"Redirect URL: {connection_request.redirect_url}")
100 +
101 +connected_account = connection_request.wait_for_connection()
102 +
103 +# Alternative: if you only have the connection request ID
104 +# connected_account = composio.connected_accounts.wait_for_connection(
105 +# connection_request.id)
106 +# Recommended when the connection_request object is no longer available
107 +
108 +print(f"Connection established: {connected_account.id}")
109 +```
110 +
111 +
112 +```typescript {10-13}
113 +import { Composio } from '@composio/core';
114 +
115 +const composio = new Composio({apiKey: "YOUR_COMPOSIO_API_KEY"});
116 +
117 +// Use the "AUTH CONFIG ID" from your dashboard
118 +const authConfigId = 'ac_UdqFwixfy3cV';
119 +// Use a unique identifier for each user in your application
120 +const userId = 'user_4567';
121 +
122 +const connRequest = await composio.connectedAccounts.initiate(
123 + userId,
124 + authConfigId
125 +);
126 +
127 +console.log(`Redirect URL: ${connRequest.redirectUrl}`);
128 +
129 +const connectedAccount = await connRequest.waitForConnection();
130 +
131 +// Alternative: if you only have the connection request ID
132 +// const connectedAccount = await composio.connectedAccounts
133 +// .waitForConnection(connRequest.id);
134 +// Recommended when the connRequest object is no longer available
135 +
136 +console.log(`Connection established: ${connectedAccount.id}`);
137 +```
138 </CodeGroup>
139
82 -## Connecting to an API Key toolkit
140
84 -For API key based toolkits, you can either request the user to provide the API key or provide your own!
141
86 -### Creating the connection
142 +### Redirecting Users (OAuth only)
143
88 -If you know the required authentication fields for your toolkit (like `apiKey` for most API-based services), you can directly create the connection:
144 +For OAuth flows, you can control where users are redirected after authentication by providing a callback Url:
145
146 <CodeGroup>
91 -<SnippetCode
92 - src="fern/snippets/tool-calling/python/auth-tools.py"
93 - startLine={23}
94 - endLine={34}
95 - title="Python"
96 -/>
97 -<SnippetCode
98 - src="fern/snippets/tool-calling/typescript/auth-tools.ts"
99 - startLine={24}
100 - endLine={37}
101 - title="TypeScript"
102 -/>
147 +```python {5}
148 +connection_request = composio.connected_accounts.initiate(
149 + user_id=user_id,
150 + auth_config_id=auth_config_id,
151 + config={"auth_scheme": "OAUTH2"},
152 + callback_url="https://www.yourapp.com/callback"
153 +)
154 +```
155 +
156 +```typescript {5}
157 +const connRequest = await composio.connectedAccounts.initiate(
158 + userId,
159 + authConfigId,
160 + {
161 + callbackUrl: 'https://www.yourapp.com/callback',
162 + }
163 +);
164 +```
165 </CodeGroup>
166
105 -## Specifying auth schemes
106 -Composio supports a wide range of auth schemes; OAuth2, API Key, HTTP Basic and many more.
107 -Each app (and toolkit) has different connection options required for each auth scheme. For example;
108 -- Shopify requires an *API key* from each user for the API Key auth scheme.
109 -- Airtable requires the Bearer token from each user for the *Bearer* auth scheme.
167
111 -The auth scheme information is typed and can be configured as follows:
168 +### API Key Connections
169 +
170 +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.
171
172 +Here is how to initiate the flow:
173
174 <CodeGroup>
115 -<SnippetCode
116 - src="fern/snippets/tool-calling/python/auth-tools.py"
117 - startLine={35}
118 - endLine={46}
119 - title="Python"
120 -/>
121 -<SnippetCode
122 - src="fern/snippets/tool-calling/typescript/auth-tools.ts"
123 - startLine={38}
124 - endLine={50}
125 - title="TypeScript"
126 -/>
175 +```python {13-19}
176 +from composio import Composio
177 +
178 +composio = Composio(api_key="your_api_key")
179 +
180 +# Use the "AUTH CONFIG ID" from your dashboard
181 +auth_config_id = "ac_ZUWpt850AqTN"
182 +# Use a unique identifier for each user in your application
183 +user_id = "user_12323"
184 +# API key provided by the user (collected from your app's UI)
185 +# or use your own key
186 +user_api_key = "user_api_key_here"
187 +
188 +connection_request = composio.connected_accounts.initiate(
189 + user_id=user_id,
190 + auth_config_id=auth_config_id,
191 + config={
192 + "auth_scheme": "API_KEY", "val": {"api_key": user_api_key}
193 + }
194 +)
195 +
196 +print(f"Connection established: {connection_request.id}")
197 +```
198 +
199 +```typescript {12-18}
200 +import { Composio, AuthScheme } from '@composio/core';
201 +
202 +const composio = new Composio({apiKey: "your_api_key"});
203 +
204 +// Use the "AUTH CONFIG ID" from your dashboard
205 +const authConfigId = 'ac_ZUWpt850AqTN';
206 +// Use a unique identifier for each user in your application
207 +const userId = 'user12345678';
208 +// API key provided by the user (collected from your app's UI)
209 +const userApiKey = 'user_api_key_here';
210 +
211 +const connectionRequest = await composio.connectedAccounts.initiate(
212 + userId, authConfigId,
213 + {
214 + config: AuthScheme.APIKey({
215 + api_key: userApiKey,
216 + }),
217 +});
218 +
219 +console.log(`Connection established: ${connectionRequest.id}`);
220 +```
221 </CodeGroup>
222
129 -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.
223
224 +## Fetching the required `config` parameters for an Auth Config
225
132 -## Redirecting users
226 +When working with any toolkits, you can **inspect an auth config** to understand its *authentication requirements* and *expected parameters*.
227
134 -To control where the users are redirected after they have authenticated, you can use the `redirectUrl` parameter in the `initiate` method.
135 -In this case, the user will be redirected to `https://www.yourapp.com/callback` after they have authenticated.
228 +Here is how you would fetch the authentication method and input fields:
229
230 <CodeGroup>
138 -<SnippetCode
139 - src="fern/snippets/tool-calling/python/callback-url.py"
140 - startLine={10}
141 - endLine={20}
142 - title="Python"
143 -/>
144 -<SnippetCode
145 - src="fern/snippets/tool-calling/typescript/callback-url.ts"
146 - startLine={10}
147 - endLine={20}
148 - title="TypeScript"
149 -/>
231 +```python {9}
232 +from composio import Composio
233 +
234 +composio = Composio(api_key="your_api_key")
235 +
236 +# Use the "AUTH CONFIG ID" from your dashboard
237 +auth_config_id = "ac_ZUWpt850AqTN"
238 +
239 +# Fetch the auth configuration details
240 +auth_config = composio.auth_configs.get(auth_config_id)
241 +
242 +# Check what authentication method this config uses
243 +print(f"Authentication method: {auth_config.auth_scheme}")
244 +
245 +# See what input fields are required
246 +print(f"Required fields: {auth_config.expected_input_fields}")
247 +```
248 +
249 +```typescript {9}
250 +import { Composio } from '@composio/core';
251 +
252 +const composio = new Composio({apiKey: "your_api_key"});
253 +
254 +// Use the "AUTH CONFIG ID" from your dashboard
255 +const authConfigId = 'ac_ZUWpt850AqTN';
256 +
257 +// Fetch the auth configuration details
258 +const authConfig = await composio.authConfigs.get(authConfigId);
259 +
260 +console.log(`Authentication method: ${authConfig.authScheme}`);
261 +console.log(`Required fields:`, authConfig.expectedInputFields);
262 +```
263 </CodeGroup>
264 +
265 +
266 +## Other Authentication Methods
267 +
268 +Composio also supports a wide range of other auth schemas:
269 +
270 +**Bearer Token** - Similar to API keys, provide the user's bearer token directly when creating the connection.
271 +
272 +**Basic Auth** - Provide username and password credentials for services that use HTTP Basic Authentication.
273 +
274 +**Custom Schemes** - Some toolkits use their own custom authentication methods. Follow the toolkit-specific requirements for such cases.
275 +
276 +<Note title="Fetching auth config">
277 +For any of these methods, [fetch the config parameter](#fetching-the-required-config-parameters-for-an-auth-config) to determine the exact fields required.
278 +Every toolkit has its own requirements, and understanding these is essential for successfully creating connections.
279 +</Note>
280 +
281 +## Next Step
282 +With authentication set up, you can now fetch and execute tools. See [Executing Tools](/docs/executing-tools) to get started.
fern/snippets/tool-calling/python/auth-tools.py deleted
-46
@@ -1,46 +0,0 @@
1 -from composio import Composio
2 -from composio.types import auth_scheme
3 -
4 -linear_auth_config_id = "ac_dqYN9oElNVlg"
5 -user_id = "0000-1111-2222"
6 -composio = Composio()
7 -
8 -# Create a new connected account
9 -connection_request = composio.connected_accounts.initiate(
10 - user_id=user_id, auth_config_id=linear_auth_config_id, config={"auth_scheme": "OAUTH2"}
11 -)
12 -print(connection_request.redirect_url)
13 -
14 -# Wait for the connection to be established
15 -connected_account = connection_request.wait_for_connection()
16 -
17 -# If you only have the connection request ID, you can also wait using:
18 -
19 -connected_account = composio.connected_accounts.wait_for_connection(connection_request.id)
20 -# Recommended for when connection_request object is destroyed
21 -
22 -# API key based toolkit
23 -# from composio.types import auth_scheme
24 -serp_auth_config_id = "ac_VWmFEC55Zgv6"
25 -
26 -# Retrieved from the user
27 -user_api_key = "sk_1234567890"
28 -
29 -connection_request = composio.connected_accounts.initiate(
30 - user_id=user_id,
31 - auth_config_id=serp_auth_config_id,
32 - config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}},
33 -)
34 -
35 -# Auth scheme config for Airtable Bearer
36 -# from composio.types import auth_scheme
37 -airtable_auth_config_id = "ac_1234567"
38 -
39 -# Retrieved from user
40 -user_bearer_token = "1234567890"
41 -
42 -airtable_connection_req = composio.connected_accounts.initiate(
43 - user_id=user_id,
44 - auth_config_id=airtable_auth_config_id,
45 - config={"auth_scheme": "BEARER_TOKEN", "val": user_bearer_token},
46 -)