@devries-cameron20 / composio Mirror · read-only / commits / f69ef8f6d
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, 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