@devries-cameron20 / composio-1 / commits / e921d2d76
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.

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>