Skip to content

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: Connected account management (#2184)

Sushmitha Malleshf69ef8f6dfb2
diff --git a/fern/docs.yml b/fern/docs.yml
index 50cfb97bc..57aa28599 100644
--- a/fern/docs.yml
+++ b/fern/docs.yml
@@ -172,6 +172,9 @@ navigation:
- page: Custom Auth Parameters
path: pages/dist/authentication/custom-auth-params.mdx
slug: custom-auth-params
+ - page: Connected Accounts
+ path: pages/dist/authentication/connected-accounts.mdx
+ slug: connected-accounts
- page: User Management
path: pages/dist/authentication/user-management.mdx
slug: user-management
diff --git a/fern/pages/src/authentication/connected-accounts.mdx b/fern/pages/src/authentication/connected-accounts.mdx
new file mode 100644
index 000000000..e0b90e2b7
--- /dev/null
+++ b/fern/pages/src/authentication/connected-accounts.mdx
@@ -0,0 +1,188 @@
+---
+title: Connected Accounts
+image: "https://og.composio.dev/api/og?title=Connected%20Accounts"
+subtitle: "Manage and monitor user connections to toolkits"
+keywords: "connected accounts, manage connections, refresh tokens, account status, account credentials, disable accounts, delete accounts"
+hide-nav-links: true
+---
+
+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.
+
+Composio automatically handles token refresh and credential management. This guide covers manual operations: listing, retrieving, refreshing, enabling, disabling, and deleting accounts.
+
+## List accounts
+
+Retrieve all connected accounts with optional filters:
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
+ title="Python"
+ startLine={12}
+ endLine={22}
+/>
+
+<SnippetCode
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
+ title="TypeScript"
+ startLine={12}
+ endLine={22}
+/>
+</CodeGroup>
+
+
+## Get account details
+
+Retrieve a connected account by ID:
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
+ title="Python"
+ startLine={25}
+ endLine={28}
+/>
+
+<SnippetCode
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
+ title="TypeScript"
+ startLine={25}
+ endLine={28}
+/>
+</CodeGroup>
+
+### Get account credentials
+
+Get account credentials for use with your own tools:
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
+ title="Python"
+ startLine={32}
+ endLine={39}
+/>
+
+<SnippetCode
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
+ title="TypeScript"
+ startLine={32}
+ endLine={40}
+/>
+</CodeGroup>
+
+## Refresh credentials
+
+Manually refresh credentials for a connected account:
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
+ title="Python"
+ startLine={43}
+ endLine={50}
+/>
+
+<SnippetCode
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
+ title="TypeScript"
+ startLine={44}
+ endLine={52}
+/>
+</CodeGroup>
+
+
+## Enable and disable accounts
+
+Change account status without deleting. Set to INACTIVE to pause access, or ACTIVE to restore. Useful for:
+- Pausing access during subscription lapses
+- Temporary disconnection
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
+ title="Python"
+ startLine={54}
+ endLine={60}
+/>
+
+<SnippetCode
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
+ title="TypeScript"
+ startLine={56}
+ endLine={62}
+/>
+</CodeGroup>
+
+<Warning>
+INACTIVE accounts cannot execute tools. Tool execution will fail until the status is changed.
+</Warning>
+
+## Delete accounts
+
+Permanently remove a connected account and revoke all credentials:
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
+ title="Python"
+ startLine={64}
+ endLine={66}
+/>
+
+<SnippetCode
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
+ title="TypeScript"
+ startLine={66}
+ endLine={68}
+/>
+</CodeGroup>
+
+<Warning>
+Deletion is permanent. Users must re-authenticate to reconnect.
+</Warning>
+
+## Multiple accounts
+
+Users can connect multiple accounts for the same toolkit (e.g., personal and work Gmail).
+
+<Note>
+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).
+</Note>
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
+ title="Python"
+ startLine={70}
+ endLine={93}
+/>
+
+<SnippetCode
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
+ title="TypeScript"
+ startLine={72}
+ endLine={99}
+/>
+</CodeGroup>
+
+### Execute with a specific account
+
+When you have multiple accounts, specify which one to use with `connected_account_id`:
+
+<CodeGroup>
+<SnippetCode
+ src="fern/snippets/authentication/python/connected-accounts-management.py"
+ title="Python"
+ startLine={95}
+ endLine={102}
+/>
+
+<SnippetCode
+ src="fern/snippets/authentication/typescript/connected-accounts-management.ts"
+ title="TypeScript"
+ startLine={101}
+ endLine={107}
+/>
+</CodeGroup>
+
diff --git a/fern/pages/src/tool-calling/authenticating-tools.mdx b/fern/pages/src/tool-calling/authenticating-tools.mdx
index 2fe88829a..4d3ac0de0 100644
--- a/fern/pages/src/tool-calling/authenticating-tools.mdx
+++ b/fern/pages/src/tool-calling/authenticating-tools.mdx
@@ -122,8 +122,6 @@ By default, users will see a Composio-branded authentication experience when con
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.
-
-
### Direct SDK Integration
**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:
successfully creating connections.
</Note>
+Learn how to [Manage connected accounts](/docs/connected-accounts) after users authenticate.
+
## Connection Statuses
After creating a connection, it will have one of the following statuses that indicates its current state:
diff --git a/fern/snippets/authentication/python/connected-accounts-management.py b/fern/snippets/authentication/python/connected-accounts-management.py
new file mode 100644
index 000000000..bd6b7589f
--- /dev/null
+++ b/fern/snippets/authentication/python/connected-accounts-management.py
@@ -0,0 +1,103 @@
+from composio import Composio
+
+composio = Composio(api_key="YOUR_COMPOSIO_API_KEY")
+
+# Define variables
+user_id = "user-123"
+auth_config_id = "auth-config-id"
+connected_account_id = "conn_abc123"
+
+# --- Listing Connected Accounts ---
+
+# List all accounts for a user
+accounts = composio.connected_accounts.list(
+ user_ids=[user_id]
+)
+
+# Filter by status
+active_accounts = composio.connected_accounts.list(
+ user_ids=[user_id],
+ statuses=["ACTIVE"]
+)
+
+# --- Retrieving a Specific Account ---
+
+account = composio.connected_accounts.get(connected_account_id)
+
+print(f"Status: {account.status}")
+print(f"Toolkit: {account.toolkit.slug}")
+
+# --- Using Account Credentials ---
+
+# Get the connected account's authentication state
+if account.state:
+ # The state contains the auth scheme and credentials
+ auth_scheme = account.state.auth_scheme
+ credentials = account.state.val
+
+ print(f"Auth scheme: {auth_scheme}")
+ print(f"Credentials: {credentials}")
+
+# --- Refreshing Credentials ---
+
+try:
+ refreshed = composio.connected_accounts.refresh(connected_account_id)
+ print(f"Redirect URL: {refreshed.redirect_url}")
+
+ # Wait for the connection to be established
+ composio.connected_accounts.wait_for_connection(refreshed.id)
+except Exception as e:
+ print(f"Failed to refresh tokens: {e}")
+
+# --- Enabling and Disabling Accounts ---
+
+# Disable an account
+disabled = composio.connected_accounts.disable(connected_account_id)
+print(f"Account disabled status: {disabled.success}")
+
+# Re-enable when needed
+enabled = composio.connected_accounts.enable(connected_account_id)
+print(f"Account enabled status: {enabled.success}")
+
+# --- Deleting Accounts ---
+
+# Delete a connected account
+composio.connected_accounts.delete(connected_account_id)
+print("Account deleted successfully")
+
+# --- Managing Multiple Accounts ---
+
+# First account
+try:
+ first_account = composio.connected_accounts.initiate(
+ user_id=user_id,
+ auth_config_id=auth_config_id
+ )
+ print(f"First account redirect URL: {first_account.redirect_url}")
+ connected_first_account = first_account.wait_for_connection()
+ print(f"First account status: {connected_first_account.status}")
+except Exception as e:
+ print(f"Error initiating first account: {e}")
+
+# Second account - must explicitly allow multiple
+try:
+ second_account = composio.connected_accounts.initiate(
+ user_id=user_id,
+ auth_config_id=auth_config_id,
+ allow_multiple=True # Required for additional accounts
+ )
+ print(f"Second account redirect URL: {second_account.redirect_url}")
+ connected_second_account = second_account.wait_for_connection()
+ print(f"Second account status: {connected_second_account.status}")
+except Exception as e:
+ print(f"Error initiating second account: {e}")
+
+# Execute tool with a specific connected account
+result = composio.tools.execute(
+ "GMAIL_GET_PROFILE",
+ user_id=user_id,
+ connected_account_id=connected_account_id, # Specify which account to use
+ version="20251111_00",
+ arguments={}
+)
+print(f"Tool executed: {result}")
\ No newline at end of file
diff --git a/fern/snippets/authentication/typescript/connected-accounts-management.ts b/fern/snippets/authentication/typescript/connected-accounts-management.ts
new file mode 100644
index 000000000..4ce01c65a
--- /dev/null
+++ b/fern/snippets/authentication/typescript/connected-accounts-management.ts
@@ -0,0 +1,108 @@
+import { Composio } from '@composio/core';
+
+const composio = new Composio({ apiKey: 'YOUR_COMPOSIO_API_KEY' });
+
+// Define variables
+const userId = 'user-123';
+const authConfigId = 'auth-config-id';
+const connectedAccountId = 'conn_abc123';
+
+// --- Listing Connected Accounts ---
+
+// List all accounts for a user
+const accounts = await composio.connectedAccounts.list({
+ userIds: [userId]
+});
+
+// Filter by status
+const activeAccounts = await composio.connectedAccounts.list({
+ userIds: [userId],
+ statuses: ['ACTIVE']
+});
+
+// --- Retrieving a Specific Account ---
+
+const account = await composio.connectedAccounts.get(connectedAccountId);
+
+console.log('Status:', account.status);
+console.log('Toolkit:', account.toolkit.slug);
+
+// --- Using Account Credentials ---
+
+// Get the connected account's authentication state
+if (account.state) {
+ // The state contains the auth scheme and credentials
+ const authScheme = account.state.authScheme;
+ const credentials = account.state.val;
+
+ console.log('Auth scheme:', authScheme);
+ console.log('Credentials:', credentials);
+}
+
+// --- Refreshing Credentials ---
+
+try {
+ const refreshed = await composio.connectedAccounts.refresh(connectedAccountId);
+ console.log('Redirect URL:', refreshed.redirect_url);
+
+ // Wait for the connection to be established
+ await composio.connectedAccounts.waitForConnection(refreshed.id);
+} catch (error) {
+ console.error('Failed to refresh tokens:', error);
+}
+
+// --- Enabling and Disabling Accounts ---
+
+// Disable an account
+const disabled = await composio.connectedAccounts.disable(connectedAccountId);
+console.log('Account disabled status:', disabled.success);
+
+// Re-enable when needed
+const enabled = await composio.connectedAccounts.enable(connectedAccountId);
+console.log('Account enabled status:', enabled.success);
+
+// --- Deleting Accounts ---
+
+// Delete a connected account
+await composio.connectedAccounts.delete(connectedAccountId);
+console.log('Account deleted successfully');
+
+// --- Managing Multiple Accounts ---
+
+// First account
+try {
+ const firstAccount = await composio.connectedAccounts.initiate(
+ userId,
+ authConfigId
+ );
+ console.log('First account redirect URL:', firstAccount.redirectUrl);
+ const connectedFirstAccount = await firstAccount.waitForConnection();
+ console.log('First account status:', connectedFirstAccount.status);
+} catch (error) {
+ console.error('Error initiating first account:', error);
+}
+
+// Second account - must explicitly allow multiple
+try {
+ const secondAccount = await composio.connectedAccounts.initiate(
+ userId,
+ authConfigId,
+ {
+ allowMultiple: true // Required for additional accounts
+ }
+ );
+ console.log('Second account redirect URL:', secondAccount.redirectUrl);
+ const connectedSecondAccount = await secondAccount.waitForConnection();
+ console.log('Second account status:', connectedSecondAccount.status);
+} catch (error) {
+ console.error('Error initiating second account:', error);
+}
+
+// Execute tool with a specific connected account
+const result = await composio.tools.execute('GMAIL_GET_PROFILE', {
+ userId: userId,
+ connectedAccountId: connectedAccountId, // Specify which account to use
+ version: '20251111_00',
+ arguments: {}
+});
+console.log('Tool executed:', result);
\ No newline at end of file