Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
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.