Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: add auth config creation, credential patching, and tool router to importing connections
- Remove outdated callout saying OAuth token import isn't supported - Add section for creating BEARER_TOKEN auth config (was missing) - Add credential patching section with Python/TS/curl examples - Add tool router session usage examples - Add changelog for BEARER_TOKEN injection + PATCH endpoint
Dhawal Upadhyay committed
Apr 9, 2026 at 21:46 UTC
e921d2d767a779fcaf40fb4f1fde789424d4b7c9
2 files changed
+190
-12
docs/content/changelog/04-07-26-bearer-token-patch.mdx
new
+41
@@ -0,0 +1,41 @@
1
+---
2
+title: "Bearer Token Connections & Credential Patching"
3
+description: "Import bearer tokens for any OAuth toolkit and update credentials in place"
4
+date: "2026-04-07"
5
+---
6
+
7
+Two features for teams managing their own authentication credentials.
8
+
9
+## Bearer Token for OAuth Toolkits
10
+
11
+All OAuth2 toolkits (Gmail, GitHub, Slack, Google Docs, and more) now support `BEARER_TOKEN` as an auth scheme. Import your own access tokens directly without setting up an OAuth app.
12
+
13
+This restores and improves the BEARER_TOKEN support that was [deprecated in December 2025](/changelog/12-31-25). The new implementation injects BEARER_TOKEN as an alternative scheme alongside OAuth2, so existing OAuth connections are unaffected.
14
+
15
+### How to use
16
+
17
+1. Create a custom auth config with `authScheme: "BEARER_TOKEN"` for the toolkit
18
+2. Create a connected account with your access token
19
+3. Pass the auth config or connection ID to `composio.create()` for use with Tool Router
20
+
21
+See the [importing connections guide](/docs/importing-existing-connections) for full examples.
22
+
23
+## Credential Patching
24
+
25
+New `PATCH /api/v3/connected_accounts/{nanoid}` endpoint and SDK method — update credentials and alias on existing connections without recreating them.
26
+
27
+```typescript
28
+await composio.connectedAccounts.update('ca_abc123', {
29
+ connection: {
30
+ state: {
31
+ authScheme: 'BEARER_TOKEN',
32
+ val: { token: 'rotated-access-token' },
33
+ },
34
+ },
35
+});
36
+```
37
+
38
+- **Credential rotation** — update expired tokens in place
39
+- **Alias management** — name connections for multi-account scenarios
40
+- **Partial updates** — omitted fields are preserved, fields set to `null` are removed
41
+- **Supported schemes** — BEARER_TOKEN, API_KEY, BASIC, BASIC_WITH_JWT, GOOGLE_SERVICE_ACCOUNT, SERVICE_ACCOUNT
docs/content/docs/importing-existing-connections.mdx
+149
-12
@@ -1,7 +1,7 @@
1
---
2
title: Importing existing connections
3
-description: Pass existing API keys, bearer tokens, or other non-OAuth credentials into Composio so your users don't need to re-authenticate
4
-keywords: [import connections, existing tokens, pass through credentials, bring your own tokens, no re-auth, pre-authenticated]
3
+description: Pass existing API keys, bearer tokens, or other credentials into Composio so your users don't need to re-authenticate
4
+keywords: [import connections, existing tokens, pass through credentials, bring your own tokens, no re-auth, pre-authenticated, patch credentials, update token, rotate credentials, oauth bearer token]
5
---
6
7
If your users have already authenticated with a service and you have their credentials (API keys, bearer tokens, etc.), you can pass those directly into Composio. No re-authentication required.
@@ -9,29 +9,79 @@ If your users have already authenticated with a service and you have their crede
9
This is useful when:
10
- Your app already stores API keys or tokens for users
11
- You're adopting Composio and want to onboard existing users without disrupting them
12
-- Another platform already holds credentials for your users' accounts
12
+- You want to use bearer tokens with OAuth toolkits (Gmail, GitHub, Slack, etc.) without setting up an OAuth app
13
14
## How it works
15
16
-Instead of asking users to authenticate again, you pass their existing credentials to `connectedAccounts.initiate()` using the `AuthScheme` helpers. Composio creates a connected account directly from those credentials.
17
-
16
```mermaid
17
graph LR
20
- A[Your existing credentials] --> B[connectedAccounts.initiate]
21
- B --> C[Connected account in Composio]
22
- C --> D[Execute tools immediately]
18
+ A[Create auth config] --> B[Create connection with credentials]
19
+ B --> C[Use in Tool Router / Execute tools]
20
+ C --> D[Update credentials when needed]
21
```
22
23
## Prerequisites
24
27
-1. **An auth config** for the toolkit you're importing into
25
+1. **A Composio API key** — from your project settings
26
2. **The existing credentials** for each user (API keys, bearer tokens, username/password, etc.)
29
-3. **A user ID** for each user, any string that uniquely identifies them in your system
27
+3. **A user ID** for each user — any string that uniquely identifies them in your system
28
+
29
+## Creating an auth config
30
31
-<Callout type="warn">
32
-Importing existing OAuth tokens (access tokens, refresh tokens) is **not currently supported**. For OAuth-based services (Google, GitHub, Slack, etc.), users must authenticate through the standard [OAuth flow](/docs/tools-direct/authenticating-tools). This page covers importing non-OAuth credentials like API keys, bearer tokens, and basic auth.
31
+Before importing credentials, you need an auth config for the toolkit. This is a one-time setup.
32
+
33
+<Callout type="info">
34
+Bearer token auth configs work with **any toolkit that supports OAuth2 or S2S auth** — including Gmail, GitHub, Slack, Google Docs, and more. This lets you import your own access tokens without setting up an OAuth app.
35
</Callout>
36
37
+<Tabs groupId="language" items={['Python', 'TypeScript', 'curl']} persist>
38
+<Tab value="Python">
39
+```python
40
+from composio import Composio
41
+
42
+composio = Composio(api_key="your-api-key")
43
+
44
+auth_config = composio.auth_configs.create("gmail", {
45
+ "type": "use_custom_auth",
46
+ "authScheme": "BEARER_TOKEN",
47
+ "credentials": {},
48
+})
49
+
50
+print(f"Auth config ID: {auth_config.id}")
51
+```
52
+</Tab>
53
+<Tab value="TypeScript">
54
+```typescript
55
+import { Composio } from '@composio/core';
56
+
57
+const composio = new Composio({ apiKey: 'your-api-key' });
58
+
59
+const authConfig = await composio.authConfigs.create('gmail', {
60
+ type: 'use_custom_auth',
61
+ authScheme: 'BEARER_TOKEN',
62
+ credentials: {},
63
+});
64
+
65
+console.log('Auth config ID:', authConfig.id);
66
+```
67
+</Tab>
68
+<Tab value="curl">
69
+```bash
70
+curl -X POST https://backend.composio.dev/api/v3/auth_configs \
71
+ -H 'x-api-key: YOUR_API_KEY' \
72
+ -H 'Content-Type: application/json' \
73
+ -d '{
74
+ "toolkit": {"slug": "gmail"},
75
+ "auth_config": {
76
+ "type": "use_custom_auth",
77
+ "authScheme": "BEARER_TOKEN",
78
+ "credentials": {}
79
+ }
80
+ }'
81
+```
82
+</Tab>
83
+</Tabs>
84
+
85
## API keys
86
87
For services that use API key authentication (e.g., SendGrid, Tavily, PostHog):
@@ -80,6 +130,8 @@ console.log('Connected:', connection.id);
130
131
## Bearer tokens
132
133
+For services where you already have an access token — including OAuth toolkits like Gmail, GitHub, Slack, and more:
134
+
135
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
136
<Tab value="Python">
137
```python
@@ -168,6 +220,91 @@ console.log('Connected:', connection.id);
220
</Tab>
221
</Tabs>
222
223
+## Updating credentials
224
+
225
+When credentials expire or rotate, update them in place without recreating the connection:
226
+
227
+<Tabs groupId="language" items={['Python', 'TypeScript', 'curl']} persist>
228
+<Tab value="Python">
229
+```python
230
+composio.connected_accounts.update(
231
+ "ca_your_connection_id",
232
+ connection={
233
+ "state": {
234
+ "authScheme": "BEARER_TOKEN",
235
+ "val": {"token": "new-access-token"},
236
+ },
237
+ },
238
+)
239
+```
240
+</Tab>
241
+<Tab value="TypeScript">
242
+```typescript
243
+await composio.connectedAccounts.update('ca_your_connection_id', {
244
+ connection: {
245
+ state: {
246
+ authScheme: 'BEARER_TOKEN',
247
+ val: { token: 'new-access-token' },
248
+ },
249
+ },
250
+});
251
+```
252
+</Tab>
253
+<Tab value="curl">
254
+```bash
255
+curl -X PATCH https://backend.composio.dev/api/v3/connected_accounts/ca_xxx \
256
+ -H 'x-api-key: YOUR_API_KEY' \
257
+ -H 'Content-Type: application/json' \
258
+ -d '{
259
+ "connection": {
260
+ "state": {
261
+ "authScheme": "BEARER_TOKEN",
262
+ "val": {"token": "new-access-token"}
263
+ }
264
+ }
265
+ }'
266
+```
267
+</Tab>
268
+</Tabs>
269
+
270
+You can also update the alias or both at once:
271
+
272
+```bash
273
+# Update alias
274
+curl -X PATCH .../api/v3/connected_accounts/ca_xxx \
275
+ -d '{"alias": "work-gmail"}'
276
+
277
+# Remove a field (set to null)
278
+curl -X PATCH .../api/v3/connected_accounts/ca_xxx \
279
+ -d '{"connection":{"state":{"authScheme":"API_KEY","val":{"subdomain":null}}}}'
280
+```
281
+
282
+Fields you omit are preserved. Fields set to `null` are removed.
283
+
284
+## Using with Tool Router
285
+
286
+Pass the auth config or connection ID when creating a session:
287
+
288
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
289
+<Tab value="Python">
290
+```python
291
+session = composio.create(
292
+ "user_123",
293
+ auth_configs={"gmail": "ac_your_auth_config"},
294
+ toolkits=["gmail"],
295
+)
296
+```
297
+</Tab>
298
+<Tab value="TypeScript">
299
+```typescript
300
+const session = await composio.create('user_123', {
301
+ authConfigs: { gmail: 'ac_your_auth_config' },
302
+ toolkits: ['gmail'],
303
+});
304
+```
305
+</Tab>
306
+</Tabs>
307
+
308
## What to read next
309
310
<Cards>