1
+---
2
+title: Authenticating Tools
3
+description: Create auth configs and connect user accounts
4
+---
5
+
6
+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.
7
+
8
+An **Auth Config** is a blueprint that defines how authentication works for a toolkit across all your users. It defines:
9
+
10
+1. **Authentication method** - `OAuth2`, `Bearer token`, `API key`, or `Basic Auth`
11
+2. **Scopes** - what actions your tools can perform
12
+3. **Credentials** - whether you'll use your own app credentials or Composio's managed auth
13
+
14
+## Creating an auth config
15
+
16
+### Using the Dashboard
17
+
18
+<Steps>
19
+<Step>
20
+### Selecting a toolkit
21
+
22
+Navigate to [Auth Configs](https://platform.composio.dev?next_page=%2Fauth-configs) tab in your dashboard and click "**Create Auth Config**". Find and select the toolkit you want to integrate (e.g., **Gmail**, **Slack**, **GitHub**).
23
+</Step>
24
+
25
+<Step>
26
+### Selecting the Authentication method
27
+
28
+Each toolkit supports different authentication methods such as **OAuth**, **API Key**, **Bearer Token**. Select from the available options for your toolkit.
29
+</Step>
30
+
31
+<Step>
32
+### Configure scopes
33
+
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
+
39
+<Step>
40
+### Authentication Management
41
+
42
+**For OAuth toolkits:**
43
+- **Development/Testing**: Use Composio's managed authentication (no setup required)
44
+- **Production**: Generate your own OAuth credentials from the toolkit's developer portal
45
+
46
+**For custom authentication schemes:**
47
+
48
+You must provide your own credentials regardless of environment.
49
+
50
+<Callout type="info">
51
+Want to remove Composio branding from OAuth screens? See [Custom Auth Configs](/docs/custom-auth-configs#white-labeling-the-oauth-consent-screen) for white-labeling options.
52
+</Callout>
53
+</Step>
54
+
55
+<Step>
56
+### You are all set!
57
+
58
+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).
59
+</Step>
60
+</Steps>
61
+
62
+<Callout type="info" title="Auth configs are reusable">
63
+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.
64
+</Callout>
65
+
66
+### When to create multiple auth configs?
67
+
68
+You should create multiple auth configs for the same toolkit when you need:
69
+
70
+- **Different authentication methods** - One OAuth config and one API key config
71
+- **Different scopes** - Separate configs for read-only vs full access
72
+- **Different OAuth apps** - Using separate client credentials for different environments
73
+- **Different permission levels** - Limiting actions for specific use cases
74
+
75
+<Cards>
76
+ <Card title="Programmatic creation" href="/docs/programmatic-auth-configs">
77
+ For managing auth configs across multiple projects, you can create them programmatically via the API
78
+ </Card>
79
+ <Card title="Production white-labeling" href="/docs/custom-auth-configs#white-labeling-the-oauth-consent-screen">
80
+ Remove Composio branding from OAuth screens for a fully white-labeled authentication experience
81
+ </Card>
82
+</Cards>
83
+
84
+## Connecting an account
85
+
86
+With an auth config created, you're ready to authenticate your users!
87
+
88
+You can either use [**Connect Link**](#hosted-authentication-connect-link) for a hosted authentication flow, or use [**Direct SDK Integration**](#direct-sdk-integration).
89
+
90
+<Callout>
91
+User authentication requires a User ID - a unique identifier that groups connected accounts together. Learn more about [User Management](/docs/user-management) to understand how to structure User IDs for your application.
92
+</Callout>
93
+
94
+**Choose the section below that matches your toolkit's authentication method:**
95
+
96
+### Hosted Authentication (Connect Link)
97
+
98
+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.
99
+
100
+<Figure
101
+ src="/images/auth-screen-example.png"
102
+ alt="Connect Link authentication screen"
103
+ caption="Connect Link authentication screen"
104
+ size="sm"
105
+/>
106
+
107
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
108
+ <Tab value="Python">
109
+```python
110
+from composio import Composio
111
+
112
+composio = Composio(api_key="your_api_key")
113
+
114
+# Use the "AUTH CONFIG ID" from your dashboard
115
+auth_config_id = "your_auth_config_id"
116
+
117
+# Use a unique identifier for each user in your application
118
+user_id = 'user-1349-129-12'
119
+
120
+connection_request = composio.connected_accounts.link(
121
+ user_id=user_id,
122
+ auth_config_id=auth_config_id,
123
+ callback_url='https://your-app.com/callback'
124
+)
125
+
126
+redirect_url = connection_request.redirect_url
127
+print(f"Visit: {redirect_url} to authenticate your account")
128
+```
129
+ </Tab>
130
+ <Tab value="TypeScript">
131
+```typescript
132
+import { Composio } from '@composio/core';
133
+
134
+const composio = new Composio({apiKey: "your_api_key"});
135
+
136
+// Use the "AUTH CONFIG ID" from your dashboard
137
+const authConfigId = 'your_auth_config_id';
138
+
139
+// Use a unique identifier for each user in your application
140
+const userId = 'user-1349-129-12';
141
+
142
+const connectionRequest = await composio.connectedAccounts.link(userId, authConfigId, {
143
+ callbackUrl: 'https://your-app.com/callback'
144
+});
145
+const redirectUrl = connectionRequest.redirectUrl;
146
+console.log(`Visit: ${redirectUrl} to authenticate your account`);
147
+```
148
+ </Tab>
149
+</Tabs>
150
+
151
+#### Customizing Connect Link
152
+
153
+By default, users will see a Composio-branded authentication experience when connecting their accounts. To customize this interface with your application's branding:
154
+
155
+1. Navigate to your Project Settings and select [Auth Screen](https://platform.composio.dev?next_page=/settings/auth-screen)
156
+2. Configure your **Logo** and **App Title**
157
+
158
+These settings will apply to all authentication flows using Connect Link, providing a white-labeled experience that maintains your brand identity throughout the authentication process.
159
+
160
+<Callout>
161
+For complete white-labeling including OAuth consent screens (removing Composio's domain), see [Custom Auth Configs - White-labeling](/docs/custom-auth-configs#white-labeling-the-oauth-consent-screen).
162
+</Callout>
163
+
164
+### Direct SDK Integration
165
+
166
+**Choose the section below that matches your toolkit's authentication method:**
167
+
168
+#### OAuth Connections
169
+
170
+For OAuth flows, you'll redirect users to complete authorization. You can specify a callback URL to control where users return after authentication:
171
+
172
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
173
+ <Tab value="Python">
174
+```python
175
+from composio import Composio
176
+
177
+composio = Composio(api_key="YOUR_COMPOSIO_API_KEY")
178
+
179
+# Use the "AUTH CONFIG ID" from your dashboard
180
+auth_config_id = "your_auth_config_id"
181
+
182
+# Use a unique identifier for each user in your application
183
+user_id = "user-1349-129-12"
184
+
185
+connection_request = composio.connected_accounts.initiate(
186
+ user_id=user_id,
187
+ auth_config_id=auth_config_id,
188
+ config={"auth_scheme": "OAUTH2"},
189
+ callback_url="https://www.yourapp.com/callback"
190
+)
191
+print(f"Redirect URL: {connection_request.redirect_url}")
192
+
193
+connected_account = connection_request.wait_for_connection()
194
+
195
+# Alternative: if you only have the connection request ID
196
+# connected_account = composio.connected_accounts.wait_for_connection(
197
+# connection_request.id)
198
+# Recommended when the connection_request object is no longer available
199
+
200
+print(f"Connection established: {connected_account.id}")
201
+```
202
+ </Tab>
203
+ <Tab value="TypeScript">
204
+```typescript
205
+import { Composio } from '@composio/core';
206
+
207
+const composio = new Composio({apiKey: "YOUR_COMPOSIO_API_KEY"});
208
+
209
+// Use the "AUTH CONFIG ID" from your dashboard
210
+const authConfigId = 'your_auth_config_id';
211
+// Use a unique identifier for each user in your application
212
+const userId = 'user_4567';
213
+
214
+const connRequest = await composio.connectedAccounts.initiate(
215
+ userId,
216
+ authConfigId,
217
+ {
218
+ callbackUrl: 'https://www.yourapp.com/callback',
219
+ }
220
+);
221
+console.log(`Redirect URL: ${connRequest.redirectUrl}`);
222
+
223
+const connectedAccount = await connRequest.waitForConnection();
224
+
225
+// Alternative: if you only have the connection request ID
226
+// const connectedAccount = await composio.connectedAccounts
227
+// .waitForConnection(connRequest.id);
228
+// Recommended when the connRequest object is no longer available
229
+
230
+console.log(`Connection established: ${connectedAccount.id}`);
231
+```
232
+ </Tab>
233
+</Tabs>
234
+
235
+#### Services with Additional Parameters
236
+
237
+Some services like Zendesk require additional parameters such as `subdomain`:
238
+
239
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
240
+ <Tab value="Python">
241
+```python
242
+# For Zendesk - include subdomain
243
+connection_request = composio.connected_accounts.initiate(
244
+ user_id=user_id,
245
+ auth_config_id=auth_config_id,
246
+ config=auth_scheme.oauth2(subdomain="mycompany") # For mycompany.zendesk.com
247
+)
248
+```
249
+ </Tab>
250
+ <Tab value="TypeScript">
251
+```typescript
252
+import { AuthScheme } from '@composio/core';
253
+// For Zendesk - include subdomain
254
+const connRequest = await composio.connectedAccounts.initiate(userId, authConfigId, {
255
+ config: AuthScheme.OAuth2({
256
+ subdomain: 'mycompany',
257
+ }),
258
+});
259
+```
260
+ </Tab>
261
+</Tabs>
262
+
263
+#### API Key Connections
264
+
265
+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.
266
+
267
+Here is how to initiate the flow:
268
+
269
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
270
+ <Tab value="Python">
271
+```python
272
+from composio import Composio
273
+
274
+composio = Composio(api_key="your_api_key")
275
+
276
+# Use the "AUTH CONFIG ID" from your dashboard
277
+auth_config_id = "your_auth_config_id"
278
+
279
+# Use a unique identifier for each user in your application
280
+user_id = "user_12323"
281
+
282
+# API key provided by the user (collected from your app's UI)
283
+# or use your own key
284
+user_api_key = "user_api_key_here"
285
+
286
+connection_request = composio.connected_accounts.initiate(
287
+ user_id=user_id,
288
+ auth_config_id=auth_config_id,
289
+ config={
290
+ "auth_scheme": "API_KEY", "val": {"api_key": user_api_key}
291
+ }
292
+)
293
+
294
+print(f"Connection established: {connection_request.id}")
295
+```
296
+ </Tab>
297
+ <Tab value="TypeScript">
298
+```typescript
299
+import { Composio, AuthScheme } from '@composio/core';
300
+
301
+const composio = new Composio({ apiKey: 'your_api_key' });
302
+
303
+// Use the "AUTH CONFIG ID" from your dashboard
304
+const authConfigId = 'your_auth_config_id';
305
+// Use a unique identifier for each user in your application
306
+const userId = 'user12345678';
307
+// API key provided by the user (collected from your app's UI)
308
+const userApiKey = 'user_api_key_here';
309
+
310
+const connectionRequest = await composio.connectedAccounts.initiate(userId, authConfigId, {
311
+ config: AuthScheme.APIKey({
312
+ api_key: userApiKey,
313
+ }),
314
+});
315
+
316
+console.log(`Connection established: ${connectionRequest.id}`);
317
+```
318
+ </Tab>
319
+</Tabs>
320
+
321
+## Fetching the required config parameters for an Auth Config
322
+
323
+When working with any toolkit, you can inspect an auth config to understand its authentication requirements and expected parameters.
324
+
325
+Here is how you would fetch the authentication method and input fields:
326
+
327
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
328
+ <Tab value="Python">
329
+```python
330
+from composio import Composio
331
+
332
+composio = Composio(api_key="your_api_key")
333
+
334
+# Use the "AUTH CONFIG ID" from your dashboard
335
+auth_config_id = "your_auth_config_id"
336
+
337
+# Fetch the auth configuration details
338
+auth_config = composio.auth_configs.get(auth_config_id)
339
+
340
+# Check what authentication method this config uses
341
+print(f"Authentication method: {auth_config.auth_scheme}")
342
+
343
+# See what input fields are required
344
+print(f"Required fields: {auth_config.expected_input_fields}")
345
+```
346
+ </Tab>
347
+ <Tab value="TypeScript">
348
+```typescript
349
+import { Composio } from '@composio/core';
350
+
351
+const composio = new Composio({ apiKey: 'your_api_key' });
352
+
353
+// Use the "AUTH CONFIG ID" from your dashboard
354
+const authConfigId = 'your_auth_config_id';
355
+
356
+// Fetch the auth configuration details
357
+const authConfig = await composio.authConfigs.get(authConfigId);
358
+
359
+console.log(`Authentication method: ${authConfig.authScheme}`);
360
+console.log(`Required fields:`, authConfig.expectedInputFields);
361
+```
362
+ </Tab>
363
+</Tabs>
364
+
365
+## Other Authentication Methods
366
+
367
+Composio also supports a wide range of other auth schemas:
368
+
369
+**Bearer Token** - Similar to API keys, provide the user's bearer token directly when creating the connection.
370
+
371
+**Basic Auth** - Provide username and password credentials for services that use HTTP Basic Authentication.
372
+
373
+**Custom Schemes** - Some toolkits use their own custom authentication methods. Follow the toolkit-specific requirements for such cases.
374
+
375
+<Callout title="Fetching auth config">
376
+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.
377
+</Callout>
378
+
379
+Learn how to [Manage connected accounts](/docs/connected-accounts) after users authenticate.
380
+
381
+## Connection Statuses
382
+
383
+After creating a connection, it will have one of the following statuses that indicates its current state:
384
+
385
+| Status | Description |
386
+|--------|-------------|
387
+| **ACTIVE** | Connection is established and working. You can execute tools with this connection. |
388
+| **INACTIVE** | Connection is temporarily disabled. Re-enable it to use the connection again. |
389
+| **PENDING** | Connection is being processed. Wait for it to become active. |
390
+| **INITIATED** | Connection request has started but not yet completed. User may still need to complete authentication. |
391
+| **EXPIRED** | Connection credentials have expired. Composio automatically attempts to refresh credentials before marking as expired. Re-authenticate to restore access. |
392
+| **FAILED** | Connection attempt failed. Check error details and try creating a new connection. |
393
+
394
+<Callout>
395
+When credentials expire for OAuth connections, Composio automatically attempts to refresh them using the refresh token. The connection is only marked as **EXPIRED** after multiple refresh attempts have failed.
396
+</Callout>
397
+
398
+### Waiting for Connection Establishment
399
+
400
+The `waitForConnection` method allows you to poll for a connection to become active after initiating authentication. This is useful when you need to ensure a connection is ready before proceeding.
401
+
402
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
403
+ <Tab value="Python">
404
+```python
405
+# Wait for the connection to be established
406
+connected_account = connection_request.wait_for_connection()
407
+print(connected_account.id)
408
+
409
+# Alternative: Wait with custom timeout
410
+# connected_account = connection_request.wait_for_connection(120) # 2 minute timeout
411
+
412
+# Alternative: If you only have the connection request ID (e.g., stored in database)
413
+# connection_id = connection_request.id # You can store this ID in your database
414
+# connected_account = composio.connected_accounts.wait_for_connection(connection_id, 60)
415
+```
416
+ </Tab>
417
+ <Tab value="TypeScript">
418
+```typescript
419
+// Wait for the connection to be established
420
+const connectedAccount = await connectionRequest.waitForConnection();
421
+console.log(connectedAccount.id);
422
+
423
+// Alternative: Wait with custom timeout
424
+// const connectedAccount = await connectionRequest.waitForConnection(120000); // 2 minutes
425
+
426
+// Alternative: If you only have the connection request ID (e.g., stored in database)
427
+// const connectionId = connectionRequest.id; // You can store this ID in your database
428
+// const connectedAccount = await composio.connectedAccounts.waitForConnection(connectionId, 60000);
429
+```
430
+ </Tab>
431
+</Tabs>
432
+
433
+The method continuously polls the Composio API until the connection:
434
+- Becomes **ACTIVE** (returns the connected account)
435
+- Enters a terminal state like **FAILED** or **EXPIRED** (throws an error)
436
+- Exceeds the specified timeout (throws a timeout error)
437
+
438
+### Checking Connection Status
439
+
440
+You can check the status of a connected account programmatically:
441
+
442
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
443
+ <Tab value="Python">
444
+```python
445
+# Get a specific connected account
446
+connected_account = composio.connected_accounts.get("your_connected_account_id")
447
+print(f"Status: {connected_account.status}")
448
+
449
+# Filter connections by user_id, auth_config_id, and status (only active accounts)
450
+filtered_connections = composio.connected_accounts.list(
451
+ user_ids=["user_123"],
452
+ auth_config_ids=["your_auth_config_id"],
453
+ statuses=["ACTIVE"]
454
+)
455
+for connection in filtered_connections.items:
456
+ print(f"{connection.id}: {connection.status}")
457
+```
458
+ </Tab>
459
+ <Tab value="TypeScript">
460
+```typescript
461
+// Get a specific connected account by its nanoid
462
+const connectedAccount = await composio.connectedAccounts.get('your_connected_account_id');
463
+console.log(`Status: ${connectedAccount.status}`);
464
+
465
+// Filter connections by user_id, auth_config_id, and status (only active accounts)
466
+const filteredConnections = await composio.connectedAccounts.list({
467
+ userIds: ['user_123'],
468
+ authConfigIds: ['your_auth_config_id'],
469
+ statuses: ['ACTIVE']
470
+});
471
+filteredConnections.items.forEach(connection => {
472
+ console.log(`${connection.id}: ${connection.status}`);
473
+});
474
+```
475
+ </Tab>
476
+</Tabs>
477
+
478
+<Callout>
479
+Only connections with **ACTIVE** status can be used to execute tools. If a connection is in any other state, you'll need to take appropriate action (re-authenticate, wait for processing, etc.) before using it.
480
+</Callout>
481
+
482
+## Next Step
483
+
484
+With authentication set up, you can now fetch and execute tools. See [Executing Tools](/docs/executing-tools) to get started.