@devries-cameron20 / composio Mirror · read-only / commits / 95cff2049
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

Update docs with the new Connect Link feature (#1928)

Sushmitha Mallesh committed Sep 14, 2025 at 16:03 UTC 95cff204926411f5b4e60da76c63265fa939660d
1 file changed +148 -116
fern/pages/src/tool-calling/authenticating-tools.mdx
+148 -116
@@ -1,17 +1,18 @@
1 ---
2 title: Authenticating Tools
3 -image: "https://og.composio.dev/api/og?title=Authenticating%20Tools" # image for socials
3 +image: 'https://og.composio.dev/api/og?title=Authenticating%20Tools' # image for socials
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.
8
10 -An **Auth Config** is a *blueprint* that defines how authentication works for a toolkit across all your users. It defines:
9 +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.
10
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*
11 +An **Auth Config** is a _blueprint_ that defines how authentication works for a toolkit across all your users. It defines:
12 +
13 +1. **Authentication method** - _OAuth2_, _Bearer token_, _API key_, or _Basic Auth_
14 +2. **Scopes** - _what actions your tools can perform_
15 +3. **Credentials** - _whether you'll use your own app credentials or Composio's managed auth_
16
17 <Frame>
18 <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
20
21 ## Creating an auth config
22
22 -### Using the Dashboard:
23 +### Using the Dashboard
24
25 <Steps>
26 <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 + 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**).
28 </Step>
29 <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 + Each toolkit supports different authentication methods such as **OAuth**, **API Key**, **Bearer
31 + Token**. Select from the available options for your toolkit.
32 </Step>
33 <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 + Depending on your authentication method, you may need to configure scopes:
35 + - **OAuth2**: Configure scopes for what data and actions your integration can access.
36 - **API Key/Bearer Token**: Permissions are typically fixed based on the key's access level.
37 </Step>
38 <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.
39 + **For OAuth toolkits:**
40 + - **Development/Testing**: Use Composio's managed authentication (no setup required)
41 + - **Production**: Generate your own OAuth credentials from the toolkit's developer portal
42 +
43 + **For custom authentication schemes:**
44 +
45 + You must provide your own credentials regardless of environment.
46 </Step>
47 <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*.
48 + Click "**Create Auth Configuration**" button and you have completed your first step! Now you can
49 + move ahead to authenticating your users by [Connecting an Account](#connecting-an-account).
50 </Step>
51 </Steps>
52
53 <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.
54 + Auth configs contain your developer credentials and app-level settings (*scopes*, *authentication
55 + method*, etc.). Once created, you can reuse the same auth config for all your users.
56 </Note>
57
58 **When to create multiple auth configs?**
@@ -56,74 +60,127 @@ An **Auth Config** is a *blueprint* that defines how authentication works for a
60 You should create multiple auth configs for the same toolkit when you need:
61
62 - **Different authentication methods** - One OAuth config and one API key config
59 -- **Different scopes** - Separate configs for read-only vs full access
63 +- **Different scopes** - Separate configs for read-only vs full access
64 - **Different OAuth apps** - Using separate client credentials for different environments
65 - **Different permission levels** - Limiting actions for specific use cases
66
67 <Card title="Programmatic creation" href="/docs/programmatic-auth-configs" icon="fa-solid fa-code">
64 - For managing auth configs across multiple projects, you can create them programmatically via the API
68 + For managing auth configs across multiple projects, you can create them programmatically via the
69 + API
70 </Card>
71
72 +## Connecting an account
73
68 -## Connecting an account:
74 +With an auth config created, you're ready to authenticate your users!
75
70 -With an auth config created, you're ready to authenticate your users!
76 +You can either use [**Connect Link**](#hosted-authentication-connect-link) for a hosted authentication flow, or use [**Direct SDK Integration**](#direct-sdk-integration).
77
72 -**Choose the section below that matches your toolkit's authentication method:**
73 -### OAuth Connections
78 +### Hosted Authentication (Connect Link)
79 +
80 +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.
81 +
82 +<CodeGroup>
83 +```python Python {11-13}
84 +from composio import Composio
85 +
86 +composio = Composio(api_key="your_api_key")
87 +
88 +# Use the "AUTH CONFIG ID" from your dashboard
89 +auth_config_id = "your_auth_config_id"
90 +
91 +# Use a unique identifier for each user in your application
92 +user_id = 'user-1349-129-12'
93 +
94 +connection_request = composio.connected_accounts.link(user_id, auth_config_id, {
95 + 'callback_url': 'https://your-app.com/callback'
96 +})
97 +redirect_url = connection_request.redirect_url
98 +print(f"Visit: {redirect_url} to authenticate your account")
99 +
100 +# Wait for the connection to be established
101 +connected_account = connection_request.wait_for_connection()
102 +print(connected_account.id)
103 +```
104 +```typescript Typescript {11-13}
105 +import { Composio } from '@composio/core';
106 +
107 +const composio = new Composio({apiKey: "your_api_key"});
108 +
109 +// Use the "AUTH CONFIG ID" from your dashboard
110 +const authConfigId = 'your_auth_config_id';
111
75 -**OAuth** connections redirect users to the toolkit's login page. Popular toolkits that use **OAuth** authentication include: *Gmail*, *Notion* etc.
112 +// Use a unique identifier for each user in your application
113 +const userId = 'user-1349-129-12';
114 +
115 +const connectionRequest = await composio.connectedAccounts.link(userId, authConfigId, {
116 + callbackUrl: 'https://your-app.com/callback'
117 +});
118 +const redirectUrl = connectionRequest.redirectUrl;
119 +console.log(`Visit: ${redirectUrl} to authenticate your account`);
120 +
121 +// Wait for the connection to be established
122 +const connectedAccount = await composio.connectedAccounts.waitForConnection(connectionRequest.id);
123 +console.log(connectedAccount.id)
124 +
125 +````
126 +
127 +</CodeGroup>
128 +
129 +### Direct SDK Integration
130 +
131 +**Choose the section below that matches your toolkit's authentication method:**
132
77 -Here's how to initiate the flow:
133 +#### OAuth Connections
134
135 +For OAuth flows, you'll redirect users to complete authorization. You can specify a callback URL to control
136 +where users return after authentication:
137
138 <CodeGroup>
81 -```python Python {11-15}
139 +```python Python {11-16}
140 from composio import Composio
141
142 composio = Composio(api_key="YOUR_COMPOSIO_API_KEY")
143
144 # Use the "AUTH CONFIG ID" from your dashboard
87 -auth_config_id = "ac_UdqFwixfy3cV"
145 +auth_config_id = "your_auth_config_id"
146
147 # Use a unique identifier for each user in your application
90 -user_id = "user_123"
148 +user_id = "user-1349-129-12"
149
150 connection_request = composio.connected_accounts.initiate(
93 - user_id=user_id,
94 - auth_config_id=auth_config_id,
95 - config={"auth_scheme": "OAUTH2"}
151 + user_id=user_id,
152 + auth_config_id=auth_config_id,
153 + config={"auth_scheme": "OAUTH2"},
154 + callback_url="https://www.yourapp.com/callback"
155 )
97 -
98 -# Redirect user to this URL
156 print(f"Redirect URL: {connection_request.redirect_url}")
157
158 connected_account = connection_request.wait_for_connection()
159
160 # Alternative: if you only have the connection request ID
161 # connected_account = composio.connected_accounts.wait_for_connection(
105 -# connection_request.id)
162 +# connection_request.id)
163 # Recommended when the connection_request object is no longer available
164
165 print(f"Connection established: {connected_account.id}")
109 -```
166
167 +````
168
112 -```typescript {10-13}
169 +```typescript {10-14}
170 import { Composio } from '@composio/core';
171
172 const composio = new Composio({apiKey: "YOUR_COMPOSIO_API_KEY"});
173
174 // Use the "AUTH CONFIG ID" from your dashboard
118 -const authConfigId = 'ac_UdqFwixfy3cV';
175 +const authConfigId = 'your_auth_config_id';
176 // Use a unique identifier for each user in your application
177 const userId = 'user_4567';
178
179 const connRequest = await composio.connectedAccounts.initiate(
123 - userId,
124 - authConfigId
180 + userId,
181 + authConfigId,
182 + callbackUrl: 'https://www.yourapp.com/callback'
183 );
126 -
184 console.log(`Redirect URL: ${connRequest.redirectUrl}`);
185
186 const connectedAccount = await connRequest.waitForConnection();
@@ -134,38 +191,11 @@ const connectedAccount = await connRequest.waitForConnection();
191 // Recommended when the connRequest object is no longer available
192
193 console.log(`Connection established: ${connectedAccount.id}`);
137 -```
138 -</CodeGroup>
139 -
140 -
194 +````
195
142 -### Redirecting Users (OAuth only)
143 -
144 -For OAuth flows, you can control where users are redirected after authentication by providing a callback Url:
145 -
146 -<CodeGroup>
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 -```
196 </CodeGroup>
197
167 -
168 -### Services with Additional Parameters
198 +#### Services with Additional Parameters
199
200 Some services like Zendesk require additional parameters such as `subdomain`:
201
@@ -173,86 +203,84 @@ Some services like Zendesk require additional parameters such as `subdomain`:
203 ```python
204 # For Zendesk - include subdomain
205 connection_request = composio.connected_accounts.initiate(
176 - user_id=user_id,
177 - auth_config_id=auth_config_id,
178 - config=auth_scheme.oauth2(subdomain="mycompany") # For mycompany.zendesk.com
206 + user_id=user_id,
207 + auth_config_id=auth_config_id,
208 + config=auth_scheme.oauth2(subdomain="mycompany") # For mycompany.zendesk.com
209 )
210 ```
211
212 ```typescript
213 import { AuthScheme } from '@composio/core';
184 -// For Zendesk - include subdomain
185 -const connRequest = await composio.connectedAccounts.initiate(
186 - userId,
187 - authConfigId,
188 - {
189 - config: AuthScheme.OAuth2({
190 - subdomain: 'mycompany'
191 - })
192 - }
193 -);
214 +// For Zendesk - include subdomain
215 +const connRequest = await composio.connectedAccounts.initiate(userId, authConfigId, {
216 + config: AuthScheme.OAuth2({
217 + subdomain: 'mycompany',
218 + }),
219 +});
220 ```
221 +
222 </CodeGroup>
223
197 -### API Key Connections
224 +#### API Key Connections
225
199 -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.
226 +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.
227
228 Here is how to initiate the flow:
229
230 <CodeGroup>
204 -```python {13-19}
231 +```python {16-22}
232 from composio import Composio
233
234 composio = Composio(api_key="your_api_key")
235
236 # Use the "AUTH CONFIG ID" from your dashboard
210 -auth_config_id = "ac_ZUWpt850AqTN"
211 -# Use a unique identifier for each user in your application
237 +auth_config_id = "your_auth_config_id"
238 +
239 +# Use a unique identifier for each user in your application
240 user_id = "user_12323"
241 +
242 # API key provided by the user (collected from your app's UI)
243 # or use your own key
244 user_api_key = "user_api_key_here"
245
246 connection_request = composio.connected_accounts.initiate(
218 - user_id=user_id,
219 - auth_config_id=auth_config_id,
220 - config={
221 - "auth_scheme": "API_KEY", "val": {"api_key": user_api_key}
222 - }
247 + user_id=user_id,
248 + auth_config_id=auth_config_id,
249 + config={
250 + "auth_scheme": "API_KEY", "val": {"api_key": user_api_key}
251 + }
252 )
253
254 print(f"Connection established: {connection_request.id}")
226 -```
255
228 -```typescript {12-18}
256 +````
257 +
258 +```typescript {12-16}
259 import { Composio, AuthScheme } from '@composio/core';
260
231 -const composio = new Composio({apiKey: "your_api_key"});
261 +const composio = new Composio({ apiKey: 'your_api_key' });
262
263 // Use the "AUTH CONFIG ID" from your dashboard
234 -const authConfigId = 'ac_ZUWpt850AqTN';
264 +const authConfigId = 'your_auth_config_id';
265 // Use a unique identifier for each user in your application
266 const userId = 'user12345678';
267 // API key provided by the user (collected from your app's UI)
268 const userApiKey = 'user_api_key_here';
269
240 -const connectionRequest = await composio.connectedAccounts.initiate(
241 - userId, authConfigId,
242 - {
243 - config: AuthScheme.APIKey({
244 - api_key: userApiKey,
245 - }),
270 +const connectionRequest = await composio.connectedAccounts.initiate(userId, authConfigId, {
271 + config: AuthScheme.APIKey({
272 + api_key: userApiKey,
273 + }),
274 });
275
276 console.log(`Connection established: ${connectionRequest.id}`);
249 -```
250 -</CodeGroup>
277 +````
278
279 +</CodeGroup>
280
281 ## Fetching the required `config` parameters for an Auth Config
282
255 -When working with any toolkits, you can **inspect an auth config** to understand its *authentication requirements* and *expected parameters*.
283 +When working with any toolkits, you can **inspect an auth config** to understand its _authentication requirements_ and _expected parameters_.
284
285 Here is how you would fetch the authentication method and input fields:
286
@@ -263,7 +291,7 @@ from composio import Composio
291 composio = Composio(api_key="your_api_key")
292
293 # Use the "AUTH CONFIG ID" from your dashboard
266 -auth_config_id = "ac_ZUWpt850AqTN"
294 +auth_config_id = "your_auth_config_id"
295
296 # Fetch the auth configuration details
297 auth_config = composio.auth_configs.get(auth_config_id)
@@ -273,24 +301,25 @@ print(f"Authentication method: {auth_config.auth_scheme}")
301
302 # See what input fields are required
303 print(f"Required fields: {auth_config.expected_input_fields}")
276 -```
304 +
305 +````
306
307 ```typescript {9}
308 import { Composio } from '@composio/core';
309
281 -const composio = new Composio({apiKey: "your_api_key"});
310 +const composio = new Composio({ apiKey: 'your_api_key' });
311
312 // Use the "AUTH CONFIG ID" from your dashboard
284 -const authConfigId = 'ac_ZUWpt850AqTN';
313 +const authConfigId = 'your_auth_config_id';
314
315 // Fetch the auth configuration details
316 const authConfig = await composio.authConfigs.get(authConfigId);
317
318 console.log(`Authentication method: ${authConfig.authScheme}`);
319 console.log(`Required fields:`, authConfig.expectedInputFields);
291 -```
292 -</CodeGroup>
320 +````
321
322 +</CodeGroup>
323
324 ## Other Authentication Methods
325
@@ -303,9 +332,12 @@ Composio also supports a wide range of other auth schemas:
332 **Custom Schemes** - Some toolkits use their own custom authentication methods. Follow the toolkit-specific requirements for such cases.
333
334 <Note title="Fetching auth config">
306 -For any of these methods, [fetch the config parameter](#fetching-the-required-config-parameters-for-an-auth-config) to determine the exact fields required.
307 -Every toolkit has its own requirements, and understanding these is essential for successfully creating connections.
335 + For any of these methods, [fetch the config
336 + parameter](#fetching-the-required-config-parameters-for-an-auth-config) to determine the exact
337 + fields required. Every toolkit has its own requirements, and understanding these is essential for
338 + successfully creating connections.
339 </Note>
340
341 ## Next Step
342 +
343 With authentication set up, you can now fetch and execute tools. See [Executing Tools](/docs/executing-tools) to get started.