@devries-cameron20 / composio Mirror · read-only / commits / 6f011f936
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, 03:15 UTC

docs: add guide for importing existing connections

Explains how to pass existing OAuth tokens, API keys, bearer tokens, and basic auth credentials into Composio without re-authenticating users. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmitha Mallesh committed Mar 9, 2026 at 18:33 UTC 6f011f93646a97d9464240f7141ab01bbca0e37a
2 files changed +222
docs/content/docs/importing-existing-connections.mdx new
+221
@@ -0,0 +1,221 @@
1 +---
2 +title: Importing existing connections
3 +description: Pass existing OAuth tokens, API keys, 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]
5 +---
6 +
7 +If your users have already authenticated with a service, say they connected their Google Drive through your app, or you already store their Slack OAuth tokens, you can pass those credentials directly into Composio. No re-authentication required.
8 +
9 +This is useful when:
10 +- Your app already has OAuth tokens for users (e.g., from a Slack or GitHub integration you built)
11 +- You're adopting Composio and want to onboard existing users without disrupting them
12 +- Another platform (like Airtable or Retool) already holds credentials for your users' accounts
13 +
14 +## How it works
15 +
16 +Instead of redirecting users through an OAuth flow, you pass their existing tokens to `connectedAccounts.initiate()` using the `AuthScheme` helpers. Composio creates a connected account directly from those credentials.
17 +
18 +```mermaid
19 +graph LR
20 + A[Your existing tokens] --> B[connectedAccounts.initiate]
21 + B --> C[Connected account in Composio]
22 + C --> D[Execute tools immediately]
23 +```
24 +
25 +## Prerequisites
26 +
27 +1. **An auth config** for the toolkit you're importing into. See the note below on which type to use.
28 +2. **The existing credentials** for each user (access tokens, refresh tokens, API keys, etc.)
29 +3. **A user ID** for each user, any string that uniquely identifies them in your system
30 +
31 +<Callout type="warn">
32 +To import OAuth tokens, you must create a [custom auth config](/docs/using-custom-auth-configuration) using the same client ID and secret that originally issued them. You cannot import OAuth tokens into Composio's managed auth config. If you use managed auth, your users will need to re-authenticate through the standard OAuth flow. This does not apply to API keys, bearer tokens, or basic auth, which work with any auth config.
33 +</Callout>
34 +
35 +## OAuth2 tokens
36 +
37 +The most common case. You have access tokens (and ideally refresh tokens) from your existing OAuth integration.
38 +
39 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
40 +<Tab value="Python">
41 +```python
42 +from composio import Composio
43 +from composio.core.models.connected_accounts import auth_scheme
44 +
45 +composio = Composio(api_key="your-api-key")
46 +
47 +connection = composio.connected_accounts.initiate(
48 + user_id="user_123",
49 + auth_config_id="ac_your_auth_config",
50 + config=auth_scheme.oauth2({
51 + "access_token": "xoxb-existing-slack-token",
52 + "refresh_token": "xoxr-existing-refresh-token", # recommended
53 + "expires_in": 3600, # optional, seconds until expiry
54 + "scope": "chat:write,channels:read", # optional
55 + }),
56 +)
57 +
58 +connected_account = connection.wait_for_connection()
59 +print(f"Connected: {connected_account.id}")
60 +```
61 +</Tab>
62 +<Tab value="TypeScript">
63 +```typescript
64 +import { Composio, AuthScheme } from '@composio/core';
65 +
66 +const composio = new Composio({ apiKey: 'your-api-key' });
67 +
68 +const connection = await composio.connectedAccounts.initiate(
69 + 'user_123',
70 + 'ac_your_auth_config',
71 + {
72 + config: AuthScheme.OAuth2({
73 + access_token: 'xoxb-existing-slack-token',
74 + refresh_token: 'xoxr-existing-refresh-token', // recommended
75 + expires_in: 3600, // optional, seconds until expiry
76 + scope: 'chat:write,channels:read', // optional
77 + }),
78 + }
79 +);
80 +
81 +const connectedAccount = await connection.waitForConnection();
82 +console.log('Connected:', connectedAccount.id);
83 +```
84 +</Tab>
85 +</Tabs>
86 +
87 +<Callout type="info">
88 +Always include a `refresh_token` when possible. Combined with your auth config's client ID and secret, Composio will automatically refresh tokens when they expire, so the imported connection stays alive long-term.
89 +</Callout>
90 +
91 +## API keys
92 +
93 +For services that use API key authentication (e.g., SendGrid, Tavily, PostHog):
94 +
95 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
96 +<Tab value="Python">
97 +```python
98 +from composio import Composio
99 +from composio.core.models.connected_accounts import auth_scheme
100 +
101 +composio = Composio(api_key="your-api-key")
102 +
103 +connection = composio.connected_accounts.initiate(
104 + user_id="user_123",
105 + auth_config_id="ac_your_auth_config",
106 + config=auth_scheme.api_key({
107 + "api_key": "sg-existing-sendgrid-key",
108 + }),
109 +)
110 +
111 +# API key connections are immediately active
112 +print(f"Connected: {connection.id}")
113 +```
114 +</Tab>
115 +<Tab value="TypeScript">
116 +```typescript
117 +import { Composio, AuthScheme } from '@composio/core';
118 +
119 +const composio = new Composio({ apiKey: 'your-api-key' });
120 +
121 +const connection = await composio.connectedAccounts.initiate(
122 + 'user_123',
123 + 'ac_your_auth_config',
124 + {
125 + config: AuthScheme.APIKey({
126 + api_key: 'sg-existing-sendgrid-key',
127 + }),
128 + }
129 +);
130 +
131 +// API key connections are immediately active
132 +console.log('Connected:', connection.id);
133 +```
134 +</Tab>
135 +</Tabs>
136 +
137 +## Bearer tokens
138 +
139 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
140 +<Tab value="Python">
141 +```python
142 +from composio import Composio
143 +from composio.core.models.connected_accounts import auth_scheme
144 +
145 +composio = Composio(api_key="your-api-key")
146 +
147 +connection = composio.connected_accounts.initiate(
148 + user_id="user_123",
149 + auth_config_id="ac_your_auth_config",
150 + config=auth_scheme.bearer_token({
151 + "token": "existing-bearer-token",
152 + }),
153 +)
154 +```
155 +</Tab>
156 +<Tab value="TypeScript">
157 +```typescript
158 +import { Composio, AuthScheme } from '@composio/core';
159 +
160 +const composio = new Composio({ apiKey: 'your-api-key' });
161 +
162 +const connection = await composio.connectedAccounts.initiate(
163 + 'user_123',
164 + 'ac_your_auth_config',
165 + {
166 + config: AuthScheme.BearerToken({
167 + token: 'existing-bearer-token',
168 + }),
169 + }
170 +);
171 +```
172 +</Tab>
173 +</Tabs>
174 +
175 +## Basic auth
176 +
177 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
178 +<Tab value="Python">
179 +```python
180 +from composio import Composio
181 +from composio.core.models.connected_accounts import auth_scheme
182 +
183 +composio = Composio(api_key="your-api-key")
184 +
185 +connection = composio.connected_accounts.initiate(
186 + user_id="user_123",
187 + auth_config_id="ac_your_auth_config",
188 + config=auth_scheme.basic({
189 + "username": "user@example.com",
190 + "password": "existing-password",
191 + }),
192 +)
193 +```
194 +</Tab>
195 +<Tab value="TypeScript">
196 +```typescript
197 +import { Composio, AuthScheme } from '@composio/core';
198 +
199 +const composio = new Composio({ apiKey: 'your-api-key' });
200 +
201 +const connection = await composio.connectedAccounts.initiate(
202 + 'user_123',
203 + 'ac_your_auth_config',
204 + {
205 + config: AuthScheme.Basic({
206 + username: 'user@example.com',
207 + password: 'existing-password',
208 + }),
209 + }
210 +);
211 +```
212 +</Tab>
213 +</Tabs>
214 +
215 +## What to read next
216 +
217 +<Cards>
218 + <Card icon={<Key />} title="Custom auth configs" href="/docs/using-custom-auth-configuration" description="Set up auth configs with your own OAuth credentials" />
219 + <Card icon={<Database />} title="Connected accounts" href="/docs/auth-configuration/connected-accounts" description="Manage connected accounts after importing" />
220 + <Card icon={<Palette />} title="White-labeling" href="/docs/white-labeling-authentication" description="Use your own branding on OAuth consent screens" />
221 +</Cards>
docs/content/docs/meta.json
+1
@@ -22,6 +22,7 @@
22 "white-labeling-authentication",
23 "managing-multiple-connected-accounts",
24 "using-custom-auth-configuration",
25 + "importing-existing-connections",
26 "webhook-verification",
27 "subscribing-to-connection-expiry-events",
28 "native-tools-vs-mcp",