> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Connected Accounts

> Manage and monitor user connections to toolkits

> [!NOTE]
>
> If you're building an agent, we recommend using [sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md) instead. See [Managing multiple connected accounts](https://composio-preview.mintlify.site/docs/authentication/managing-multiple-connected-accounts.md) for how sessions handle account selection automatically.

Connected accounts are authenticated connections between your users and toolkits. After users authenticate (see [Authenticating tools](https://composio-preview.mintlify.site/docs/tools-direct/authenticating-tools.md)), 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:

> [tab] Python
>
> ```python theme={null}
> # 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"]
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const userId = 'user_123';
> // 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']
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # List all accounts for a user
> curl -X GET "https://backend.composio.dev/api/v3.1/connected_accounts?user_ids=user_123" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
>
> # Filter by status
> curl -X GET "https://backend.composio.dev/api/v3.1/connected_accounts?user_ids=user_123&statuses=ACTIVE" \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

## Get account details

Retrieve a connected account by ID:

> [tab] Python
>
> ```python theme={null}
> account = composio.connected_accounts.get(connected_account_id)
>
> print(f"Status: {account.status}")
> print(f"Toolkit: {account.toolkit.slug}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const connectedAccountId = 'ca_123';
> const account = await composio.connectedAccounts.get(connectedAccountId);
>
> console.log('Status:', account.status);
> console.log('Toolkit:', account.toolkit.slug);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X GET https://backend.composio.dev/api/v3.1/connected_accounts/ca_123 \
>   -H "x-api-key: $COMPOSIO_API_KEY" | jq '{status, toolkit: .toolkit.slug}'
> ```

### Get account credentials

Connected-account responses describe the authentication state. Sensitive credential fields in `account.state.val` are [redacted by default](#credential-masking), for both Composio-managed and custom auth configs. This object is not a source of usable provider tokens for your own tools.

To call a provider API, use [Proxy Execute](https://composio-preview.mintlify.site/docs/extending-sessions/proxy-execute.md), which injects credentials server-side. For custom business logic, use [session extension tools](https://composio-preview.mintlify.site/docs/extending-sessions/custom-tools-and-toolkits.md). See [Token custody architecture](https://composio-preview.mintlify.site/docs/security/token-custody.md) for the boundaries between your application, Composio, and the provider.

## Refresh credentials

> [!WARNING]
>
> `composio.connected_accounts.refresh()` in Python and `composio.connectedAccounts.refresh()` in TypeScript are deprecated. Re-initiate authentication with `link()` or `composio.toolkits.authorize()` instead. The refresh endpoint no longer validates credentials. TypeScript ignores `validateCredentials` and logs a warning when you set it.

Manually refresh credentials for a connected account:

> [tab] Python
>
> ```python theme={null}
> 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}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const connectedAccountId = 'ca_123';
> 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);
> }
> ```

> [tab] API
>
> ```bash theme={null}
> # Deprecated endpoint: returns a redirect URL for re-authentication
> curl -X POST https://backend.composio.dev/api/v3.1/connected_accounts/ca_123/refresh \
>   -H "x-api-key: $COMPOSIO_API_KEY" | jq -r '.redirect_url'
>
> # Check whether the connection is ACTIVE again
> curl -X GET https://backend.composio.dev/api/v3.1/connected_accounts/ca_123 \
>   -H "x-api-key: $COMPOSIO_API_KEY" | jq -r '.status'
> ```

## 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

> [tab] Python
>
> ```python theme={null}
> # 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}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const connectedAccountId = 'ca_123';
> // 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);
> ```

> [tab] API
>
> ```bash theme={null}
> # Disable an account
> curl -X PATCH https://backend.composio.dev/api/v3.1/connected_accounts/ca_123/status \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"enabled": false}'
>
> # Re-enable when needed
> curl -X PATCH https://backend.composio.dev/api/v3.1/connected_accounts/ca_123/status \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"enabled": true}'
> ```

> [!WARNING]
>
> INACTIVE accounts cannot execute tools. Tool execution will fail until the status is changed.

## Revoke accounts

To revoke upstream tokens and mark a connection `REVOKED`, call `composio.connected_accounts.revoke(connected_account_id)` in Python or `await composio.connectedAccounts.revoke(connectedAccountId)` in TypeScript. Upstream token revocation is best effort. The call fails if the toolkit does not support programmatic revocation or the account is not in a revokable state.

## Complete deferred OAuth

If your project has an OAuth callback verifier configured, Composio redirects to your verifier with a single-use session URI before activating the connection. Verify the person's identity in your application, then redeem the URI with `composio.connected_accounts.complete_auth(user_id=user_id, session_uri=session_uri)` in Python or `await composio.connectedAccounts.completeAuth({ userId, sessionUri })` in TypeScript.

Composio checks project ownership and the connection's user ID before completing the token exchange. An expired or already redeemed URI returns a `404`.

## Delete accounts

Permanently remove a connected account:

> [tab] Python
>
> ```python theme={null}
> # Delete a connected account
> composio.connected_accounts.delete(connected_account_id)
> print("Account deleted successfully")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const connectedAccountId = 'ca_123';
> // Delete a connected account
> await composio.connectedAccounts.delete(connectedAccountId);
> console.log('Account deleted successfully');
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X DELETE https://backend.composio.dev/api/v3.1/connected_accounts/ca_123 \
>   -H "x-api-key: $COMPOSIO_API_KEY"
> ```

> [!WARNING]
>
> Deletion is permanent and cannot be undone.

## Credential masking

By default, sensitive fields in connected account responses are partially masked for security. This affects fields like `access_token`, `refresh_token`, `api_key`, `bearer_token`, `password`, and other secrets.

Instead of returning full values, the API returns the first 4 characters followed by `...`:

```json theme={null}
{
  "access_token": "gho_...",
  "refresh_token": "ghr_...",
  "api_key": "sk-l..."
}
```

Values shorter than 4 characters are replaced with `REDACTED`.

This applies to the Get Connected Account and List Connected Accounts endpoints for both Composio-managed and custom auth configs. The API redacts these fields before returning the response to your application.

If your use case requires calling a provider API directly, use [Proxy execute](https://composio-preview.mintlify.site/docs/extending-sessions/proxy-execute.md). Composio injects the connected account's credentials server-side.

## Multiple accounts

Users can connect multiple accounts for the same toolkit (e.g., personal and work Gmail).

> [!WARNING]
>
> **For Composio-managed OAuth, prefer `link()`.** The `initiate()` examples below will stop working for Composio-managed OAuth auth configs starting **2026-05-08** (new orgs) / **2026-07-03** (all orgs). `link()` provides hosted authentication and is unaffected by the rollout. Like `initiate()`, it refuses to create a second active connection for the same user and auth config unless you pass `allow_multiple=True` (Python) or `allowMultiple: true` (TypeScript). See [Connect Link authentication](https://composio-preview.mintlify.site/docs/tools-direct/authenticating-tools.md#hosted-authentication-connect-link), the [migration guide](https://composio-preview.mintlify.site/docs/auth-configuration/migrating-initiate-to-link.md), or the [changelog entry](https://composio-preview.mintlify.site/docs/changelog/2026/04/24).
>
> The `initiate()` examples remain accurate for **custom auth configs** (your own OAuth app) and **non-OAuth schemes** (API key, bearer, basic) — those are unaffected.

> [tab] Python
>
> ```python theme={null}
> # 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}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const userId = 'user_123';
> const authConfigId = 'ac_123';
> // 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);
> }
> ```

> [tab] API
>
> ```bash theme={null}
> # Each call creates a new connection for the same user and auth config.
> # The API does not block duplicates; allow_multiple is an SDK-side check.
> curl -X POST https://backend.composio.dev/api/v3.1/connected_accounts \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"auth_config": {"id": "ac_123"}, "connection": {"user_id": "user_123"}}' | jq -r '.redirect_url'
> ```

> [!NOTE]
>
> For session-based apps, see [Managing multiple connected accounts](https://composio-preview.mintlify.site/docs/authentication/managing-multiple-connected-accounts.md) for how to pass a specific account to a session.

### Execute with a specific account

When you have multiple accounts, specify which one to use with `connected_account_id`:

> [tab] Python
>
> ```python theme={null}
> # 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}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const userId = 'user_123';
> const connectedAccountId = 'ca_123';
> // 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);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -X POST https://backend.composio.dev/api/v3.1/tools/execute/GMAIL_GET_PROFILE \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user_123", "connected_account_id": "ca_123", "version": "20251111_00", "arguments": {}}'
> ```

## Next

> [card] [Authenticating tools](https://composio-preview.mintlify.site/docs/tools-direct/authenticating-tools.md)
>
> Create auth configs and connect user accounts
