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, 18:15 UTC
Docs: Connected account management (#2184)
Sushmitha Mallesh committed
Nov 18, 2025 at 21:05 UTC
f69ef8f6dfb22ad56fe1543f6eee7c2d0eb4f305
5 files changed
+404
-2
fern/docs.yml
+3
@@ -172,6 +172,9 @@ navigation:
172
- page: Custom Auth Parameters
173
path: pages/dist/authentication/custom-auth-params.mdx
174
slug: custom-auth-params
175
+ - page: Connected Accounts
176
+ path: pages/dist/authentication/connected-accounts.mdx
177
+ slug: connected-accounts
178
- page: User Management
179
path: pages/dist/authentication/user-management.mdx
180
slug: user-management
fern/pages/src/authentication/connected-accounts.mdx
new
+188
@@ -0,0 +1,188 @@
1
+---
2
+title: Connected Accounts
3
+image: "https://og.composio.dev/api/og?title=Connected%20Accounts"
4
+subtitle: "Manage and monitor user connections to toolkits"
5
+keywords: "connected accounts, manage connections, refresh tokens, account status, account credentials, disable accounts, delete accounts"
6
+hide-nav-links: true
7
+---
8
+
9
+Connected accounts are authenticated connections between your users and toolkits. After users authenticate (see [Authenticating tools](/docs/authenticating-tools)), you can manage these accounts throughout their lifecycle.
10
+
11
+Composio automatically handles token refresh and credential management. This guide covers manual operations: listing, retrieving, refreshing, enabling, disabling, and deleting accounts.
12
+
13
+## List accounts
14
+
15
+Retrieve all connected accounts with optional filters:
16
+
17
+<CodeGroup>
18
+<SnippetCode
19
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
20
+ title="Python"
21
+ startLine={12}
22
+ endLine={22}
23
+/>
24
+
25
+<SnippetCode
26
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
27
+ title="TypeScript"
28
+ startLine={12}
29
+ endLine={22}
30
+/>
31
+</CodeGroup>
32
+
33
+
34
+## Get account details
35
+
36
+Retrieve a connected account by ID:
37
+
38
+<CodeGroup>
39
+<SnippetCode
40
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
41
+ title="Python"
42
+ startLine={25}
43
+ endLine={28}
44
+/>
45
+
46
+<SnippetCode
47
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
48
+ title="TypeScript"
49
+ startLine={25}
50
+ endLine={28}
51
+/>
52
+</CodeGroup>
53
+
54
+### Get account credentials
55
+
56
+Get account credentials for use with your own tools:
57
+
58
+<CodeGroup>
59
+<SnippetCode
60
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
61
+ title="Python"
62
+ startLine={32}
63
+ endLine={39}
64
+/>
65
+
66
+<SnippetCode
67
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
68
+ title="TypeScript"
69
+ startLine={32}
70
+ endLine={40}
71
+/>
72
+</CodeGroup>
73
+
74
+## Refresh credentials
75
+
76
+Manually refresh credentials for a connected account:
77
+
78
+<CodeGroup>
79
+<SnippetCode
80
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
81
+ title="Python"
82
+ startLine={43}
83
+ endLine={50}
84
+/>
85
+
86
+<SnippetCode
87
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
88
+ title="TypeScript"
89
+ startLine={44}
90
+ endLine={52}
91
+/>
92
+</CodeGroup>
93
+
94
+
95
+## Enable and disable accounts
96
+
97
+Change account status without deleting. Set to INACTIVE to pause access, or ACTIVE to restore. Useful for:
98
+- Pausing access during subscription lapses
99
+- Temporary disconnection
100
+
101
+<CodeGroup>
102
+<SnippetCode
103
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
104
+ title="Python"
105
+ startLine={54}
106
+ endLine={60}
107
+/>
108
+
109
+<SnippetCode
110
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
111
+ title="TypeScript"
112
+ startLine={56}
113
+ endLine={62}
114
+/>
115
+</CodeGroup>
116
+
117
+<Warning>
118
+INACTIVE accounts cannot execute tools. Tool execution will fail until the status is changed.
119
+</Warning>
120
+
121
+## Delete accounts
122
+
123
+Permanently remove a connected account and revoke all credentials:
124
+
125
+<CodeGroup>
126
+<SnippetCode
127
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
128
+ title="Python"
129
+ startLine={64}
130
+ endLine={66}
131
+/>
132
+
133
+<SnippetCode
134
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
135
+ title="TypeScript"
136
+ startLine={66}
137
+ endLine={68}
138
+/>
139
+</CodeGroup>
140
+
141
+<Warning>
142
+Deletion is permanent. Users must re-authenticate to reconnect.
143
+</Warning>
144
+
145
+## Multiple accounts
146
+
147
+Users can connect multiple accounts for the same toolkit (e.g., personal and work Gmail).
148
+
149
+<Note>
150
+Use `link()` for creating accounts, as it provides hosted authentication and allows multiple accounts by default. See [Connect Link authentication](/docs/authenticating-tools#hosted-authentication-connect-link).
151
+</Note>
152
+
153
+<CodeGroup>
154
+<SnippetCode
155
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
156
+ title="Python"
157
+ startLine={70}
158
+ endLine={93}
159
+/>
160
+
161
+<SnippetCode
162
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
163
+ title="TypeScript"
164
+ startLine={72}
165
+ endLine={99}
166
+/>
167
+</CodeGroup>
168
+
169
+### Execute with a specific account
170
+
171
+When you have multiple accounts, specify which one to use with `connected_account_id`:
172
+
173
+<CodeGroup>
174
+<SnippetCode
175
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
176
+ title="Python"
177
+ startLine={95}
178
+ endLine={102}
179
+/>
180
+
181
+<SnippetCode
182
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
183
+ title="TypeScript"
184
+ startLine={101}
185
+ endLine={107}
186
+/>
187
+</CodeGroup>
188
+
fern/pages/src/tool-calling/authenticating-tools.mdx
+2
-2
@@ -122,8 +122,6 @@ By default, users will see a Composio-branded authentication experience when con
122
123
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.
124
125
-
126
-
125
### Direct SDK Integration
126
127
**Choose the section below that matches your toolkit's authentication method:**
@@ -338,6 +336,8 @@ Composio also supports a wide range of other auth schemas:
336
successfully creating connections.
337
</Note>
338
339
+Learn how to [Manage connected accounts](/docs/connected-accounts) after users authenticate.
340
+
341
## Connection Statuses
342
343
After creating a connection, it will have one of the following statuses that indicates its current state:
fern/snippets/authentication/python/connected-accounts-management.py
new
+103
@@ -0,0 +1,103 @@
1
+from composio import Composio
2
+
3
+composio = Composio(api_key="YOUR_COMPOSIO_API_KEY")
4
+
5
+# Define variables
6
+user_id = "user-123"
7
+auth_config_id = "auth-config-id"
8
+connected_account_id = "conn_abc123"
9
+
10
+# --- Listing Connected Accounts ---
11
+
12
+# List all accounts for a user
13
+accounts = composio.connected_accounts.list(
14
+ user_ids=[user_id]
15
+)
16
+
17
+# Filter by status
18
+active_accounts = composio.connected_accounts.list(
19
+ user_ids=[user_id],
20
+ statuses=["ACTIVE"]
21
+)
22
+
23
+# --- Retrieving a Specific Account ---
24
+
25
+account = composio.connected_accounts.get(connected_account_id)
26
+
27
+print(f"Status: {account.status}")
28
+print(f"Toolkit: {account.toolkit.slug}")
29
+
30
+# --- Using Account Credentials ---
31
+
32
+# Get the connected account's authentication state
33
+if account.state:
34
+ # The state contains the auth scheme and credentials
35
+ auth_scheme = account.state.auth_scheme
36
+ credentials = account.state.val
37
+
38
+ print(f"Auth scheme: {auth_scheme}")
39
+ print(f"Credentials: {credentials}")
40
+
41
+# --- Refreshing Credentials ---
42
+
43
+try:
44
+ refreshed = composio.connected_accounts.refresh(connected_account_id)
45
+ print(f"Redirect URL: {refreshed.redirect_url}")
46
+
47
+ # Wait for the connection to be established
48
+ composio.connected_accounts.wait_for_connection(refreshed.id)
49
+except Exception as e:
50
+ print(f"Failed to refresh tokens: {e}")
51
+
52
+# --- Enabling and Disabling Accounts ---
53
+
54
+# Disable an account
55
+disabled = composio.connected_accounts.disable(connected_account_id)
56
+print(f"Account disabled status: {disabled.success}")
57
+
58
+# Re-enable when needed
59
+enabled = composio.connected_accounts.enable(connected_account_id)
60
+print(f"Account enabled status: {enabled.success}")
61
+
62
+# --- Deleting Accounts ---
63
+
64
+# Delete a connected account
65
+composio.connected_accounts.delete(connected_account_id)
66
+print("Account deleted successfully")
67
+
68
+# --- Managing Multiple Accounts ---
69
+
70
+# First account
71
+try:
72
+ first_account = composio.connected_accounts.initiate(
73
+ user_id=user_id,
74
+ auth_config_id=auth_config_id
75
+ )
76
+ print(f"First account redirect URL: {first_account.redirect_url}")
77
+ connected_first_account = first_account.wait_for_connection()
78
+ print(f"First account status: {connected_first_account.status}")
79
+except Exception as e:
80
+ print(f"Error initiating first account: {e}")
81
+
82
+# Second account - must explicitly allow multiple
83
+try:
84
+ second_account = composio.connected_accounts.initiate(
85
+ user_id=user_id,
86
+ auth_config_id=auth_config_id,
87
+ allow_multiple=True # Required for additional accounts
88
+ )
89
+ print(f"Second account redirect URL: {second_account.redirect_url}")
90
+ connected_second_account = second_account.wait_for_connection()
91
+ print(f"Second account status: {connected_second_account.status}")
92
+except Exception as e:
93
+ print(f"Error initiating second account: {e}")
94
+
95
+# Execute tool with a specific connected account
96
+result = composio.tools.execute(
97
+ "GMAIL_GET_PROFILE",
98
+ user_id=user_id,
99
+ connected_account_id=connected_account_id, # Specify which account to use
100
+ version="20251111_00",
101
+ arguments={}
102
+)
103
+print(f"Tool executed: {result}")
\ No newline at end of file
fern/snippets/authentication/typescript/connected-accounts-management.ts
new
+108
@@ -0,0 +1,108 @@
1
+import { Composio } from '@composio/core';
2
+
3
+const composio = new Composio({ apiKey: 'YOUR_COMPOSIO_API_KEY' });
4
+
5
+// Define variables
6
+const userId = 'user-123';
7
+const authConfigId = 'auth-config-id';
8
+const connectedAccountId = 'conn_abc123';
9
+
10
+// --- Listing Connected Accounts ---
11
+
12
+// List all accounts for a user
13
+const accounts = await composio.connectedAccounts.list({
14
+ userIds: [userId]
15
+});
16
+
17
+// Filter by status
18
+const activeAccounts = await composio.connectedAccounts.list({
19
+ userIds: [userId],
20
+ statuses: ['ACTIVE']
21
+});
22
+
23
+// --- Retrieving a Specific Account ---
24
+
25
+const account = await composio.connectedAccounts.get(connectedAccountId);
26
+
27
+console.log('Status:', account.status);
28
+console.log('Toolkit:', account.toolkit.slug);
29
+
30
+// --- Using Account Credentials ---
31
+
32
+// Get the connected account's authentication state
33
+if (account.state) {
34
+ // The state contains the auth scheme and credentials
35
+ const authScheme = account.state.authScheme;
36
+ const credentials = account.state.val;
37
+
38
+ console.log('Auth scheme:', authScheme);
39
+ console.log('Credentials:', credentials);
40
+}
41
+
42
+// --- Refreshing Credentials ---
43
+
44
+try {
45
+ const refreshed = await composio.connectedAccounts.refresh(connectedAccountId);
46
+ console.log('Redirect URL:', refreshed.redirect_url);
47
+
48
+ // Wait for the connection to be established
49
+ await composio.connectedAccounts.waitForConnection(refreshed.id);
50
+} catch (error) {
51
+ console.error('Failed to refresh tokens:', error);
52
+}
53
+
54
+// --- Enabling and Disabling Accounts ---
55
+
56
+// Disable an account
57
+const disabled = await composio.connectedAccounts.disable(connectedAccountId);
58
+console.log('Account disabled status:', disabled.success);
59
+
60
+// Re-enable when needed
61
+const enabled = await composio.connectedAccounts.enable(connectedAccountId);
62
+console.log('Account enabled status:', enabled.success);
63
+
64
+// --- Deleting Accounts ---
65
+
66
+// Delete a connected account
67
+await composio.connectedAccounts.delete(connectedAccountId);
68
+console.log('Account deleted successfully');
69
+
70
+// --- Managing Multiple Accounts ---
71
+
72
+// First account
73
+try {
74
+ const firstAccount = await composio.connectedAccounts.initiate(
75
+ userId,
76
+ authConfigId
77
+ );
78
+ console.log('First account redirect URL:', firstAccount.redirectUrl);
79
+ const connectedFirstAccount = await firstAccount.waitForConnection();
80
+ console.log('First account status:', connectedFirstAccount.status);
81
+} catch (error) {
82
+ console.error('Error initiating first account:', error);
83
+}
84
+
85
+// Second account - must explicitly allow multiple
86
+try {
87
+ const secondAccount = await composio.connectedAccounts.initiate(
88
+ userId,
89
+ authConfigId,
90
+ {
91
+ allowMultiple: true // Required for additional accounts
92
+ }
93
+ );
94
+ console.log('Second account redirect URL:', secondAccount.redirectUrl);
95
+ const connectedSecondAccount = await secondAccount.waitForConnection();
96
+ console.log('Second account status:', connectedSecondAccount.status);
97
+} catch (error) {
98
+ console.error('Error initiating second account:', error);
99
+}
100
+
101
+// Execute tool with a specific connected account
102
+const result = await composio.tools.execute('GMAIL_GET_PROFILE', {
103
+ userId: userId,
104
+ connectedAccountId: connectedAccountId, // Specify which account to use
105
+ version: '20251111_00',
106
+ arguments: {}
107
+});
108
+console.log('Tool executed:', result);
\ No newline at end of file