Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
Docs: Connected account management (#2184)
Sushmitha Malleshf69ef8f6dfb2
diff --git a/fern/docs.yml b/fern/docs.ymlindex 50cfb97bc..57aa28599 100644--- a/fern/docs.yml+++ b/fern/docs.yml@@ -172,6 +172,9 @@ navigation:- page: Custom Auth Parameterspath: pages/dist/authentication/custom-auth-params.mdxslug: custom-auth-params+ - page: Connected Accounts+ path: pages/dist/authentication/connected-accounts.mdx+ slug: connected-accounts- page: User Managementpath: pages/dist/authentication/user-management.mdxslug: user-managementdiff --git a/fern/pages/src/authentication/connected-accounts.mdx b/fern/pages/src/authentication/connected-accounts.mdxnew file mode 100644index 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.mdxindex 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 conThese 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 StatusesAfter 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.pynew file mode 100644index 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 filediff --git a/fern/snippets/authentication/typescript/connected-accounts-management.ts b/fern/snippets/authentication/typescript/connected-accounts-management.tsnew file mode 100644index 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