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

# Authenticating Tools

> Create auth configs and connect user accounts

> [!NOTE]
>
> **Legacy API: prefer sessions**
>
> This guide covers legacy direct-authentication methods, which remain supported for existing integrations. For new integrations, use [sessions](https://composio-preview.mintlify.site/docs/configuring-sessions.md) with [in-chat authentication](https://composio-preview.mintlify.site/docs/authentication#in-chat-authentication) or [manual authentication](https://composio-preview.mintlify.site/docs/authentication/manually-authenticating.md). If you use direct authentication today, consider [migrating to sessions](https://composio-preview.mintlify.site/docs/migration-guide/direct-to-sessions.md).

The first step in authenticating your users is to create an **Auth Config**. Every toolkit has its own authentication method such as `OAuth`, `API key`, `Basic Auth`, or custom schemes.

An **Auth Config** is a blueprint that defines how authentication works for a toolkit across all your users. It defines:

1. **Authentication method** - `OAuth2`, `Bearer token`, `API key`, or `Basic Auth`
2. **Scopes** - what actions your tools can perform
3. **Credentials** - whether you'll use your own app credentials or Composio's managed auth

> [!NOTE]
>
> **Connecting accounts with managed OAuth**
>
> For Composio-managed OAuth, use `connectedAccounts.link()` in TypeScript or `connected_accounts.link()` in Python. Follow [Hosted Authentication](#hosted-authentication-connect-link) below. `initiate()` remains available for custom OAuth configs and non-OAuth schemes. See the [migration guide](https://composio-preview.mintlify.site/docs/auth-configuration/migrating-initiate-to-link.md).

## Creating an auth config

### Using the Dashboard

**1. Selecting a toolkit**

Navigate to [Auth Configs](https://dashboard.composio.dev/~/project/auth-configs?utm_source=docs\&utm_medium=content\&utm_campaign=docs-tools-direct-authenticating-tools) tab in your dashboard and click "**Create Auth Config**". Find and select the toolkit you want to integrate (e.g., **Gmail**, **Slack**, **GitHub**).

**2. Selecting the Authentication method**

Each toolkit supports different authentication methods such as **OAuth**, **API Key**, **Bearer Token**. Select from the available options for your toolkit.

**3. Configure scopes**

Depending on your authentication method, you may need to configure scopes:

* **OAuth2**: Configure scopes for what data and actions your app can access.
* **API Key/Bearer Token**: Permissions are typically fixed based on the key's access level.

**4. Authentication Management**

**For OAuth toolkits:**

* **Development/Testing**: Use Composio's managed authentication (no setup required)
* **Production**: Generate your own OAuth credentials from the toolkit's developer portal

**For custom authentication schemes:**

You must provide your own credentials regardless of environment.

> [!NOTE]
>
> Want to remove Composio branding from OAuth screens? See [White-labeling](https://composio-preview.mintlify.site/docs/auth-configuration/white-labeling.md) for details.

**5. You are all set!**

Click "**Create Auth Configuration**" button and you have completed your first step! Now you can move ahead to authenticating your users by [Connecting an Account](#connecting-an-account).

> [!NOTE]
>
> **Auth configs are reusable**
>
> Auth configs contain your developer credentials and app-level settings (*scopes*, *authentication method*, etc.). Once created, you can reuse the same auth config for all your users.

### When to create multiple auth configs?

You should create multiple auth configs for the same toolkit when you need:

* **Different authentication methods** - One OAuth config and one API key config
* **Different scopes** - Separate configs for read-only vs full access
* **Different OAuth apps** - Using separate client credentials for different environments
* **Different permission levels** - Limiting actions for specific use cases

> [card] [Programmatic creation](https://composio-preview.mintlify.site/docs/authentication/programmatic-auth-configs.md)
>
> For managing auth configs across multiple projects, you can create them programmatically via the API

> [card] [Production white-labeling](https://composio-preview.mintlify.site/docs/auth-configuration/white-labeling.md)
>
> Remove Composio branding from OAuth screens for a fully white-labeled authentication experience

## Connecting an account

With an auth config created, you're ready to authenticate your users!

You can either use [**Connect Link**](#hosted-authentication-connect-link) for a hosted authentication flow, or use [**Direct SDK Setup**](#direct-sdk-setup).

> [!NOTE]
>
> User authentication requires a userID - a unique identifier that groups connected accounts together. Learn more about [User scoping](https://composio-preview.mintlify.site/docs/how-composio-works.md) to understand how to structure userIDs for your application.

**Choose the section below that matches your toolkit's authentication method:**

### Hosted Authentication (Connect Link)

Redirect users to a Composio-hosted URL that handles the entire authentication process—OAuth flows, API key collection, or custom fields like subdomain. You can specify a callback URL to control where users return after authentication.

![Connect Link authentication screen](https://mintcdn.com/composio-preview/8QmhU-UXaqTdWL9_/images/auth-screen-example.png?fit=max\&auto=format\&n=8QmhU-UXaqTdWL9_\&q=85\&s=a40931adbb5c38809c479e4a12f77beb)

Connect Link authentication screen

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio(api_key="your_api_key")
>
> # Use the "AUTH CONFIG ID" from your dashboard
> auth_config_id = "your_auth_config_id"
>
> # Use a unique identifier for each user in your application
> user_id = 'user-1349-129-12'
>
> connection_request = composio.connected_accounts.link(
>     user_id=user_id,
>     auth_config_id=auth_config_id,
>     callback_url='https://your-app.com/callback'
> )
>
> redirect_url = connection_request.redirect_url
> print(f"Visit: {redirect_url} to authenticate your account")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio({apiKey: "your_api_key"});
>
> // Use the "AUTH CONFIG ID" from your dashboard
> const authConfigId = 'your_auth_config_id';
>
> // Use a unique identifier for each user in your application
> const userId = 'user-1349-129-12';
>
> const connectionRequest = await composio.connectedAccounts.link(userId, authConfigId, {
>   callbackUrl: 'https://your-app.com/callback'
> });
> const redirectUrl = connectionRequest.redirectUrl;
> console.log(`Visit: ${redirectUrl} to authenticate your account`);
> ```

> [tab] API
>
> ```bash theme={null}
> REDIRECT_URL=$(curl -s -X POST https://backend.composio.dev/api/v3.1/connected_accounts/link \
>   -H "x-api-key: $COMPOSIO_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{"user_id": "user-1349-129-12", "auth_config_id": "your_auth_config_id", "callback_url": "https://your-app.com/callback"}' \
>   | jq -r '.redirect_url')
> echo "Visit: $REDIRECT_URL to authenticate your account"
> ```

By default, `link()` refuses to create a second active connection for the same user and auth config. If your user intentionally needs another account on that auth config, pass `allow_multiple=True` in Python or `allowMultiple: true` in TypeScript. Enable [multi-account mode](https://composio-preview.mintlify.site/docs/authentication/managing-multiple-connected-accounts.md) when a session needs to use those accounts together.

#### Customizing Connect Link

You can customize the Connect Link with your logo and app title, or fully white-label OAuth consent screens with your own developer apps.

> [card] [White-labeling](https://composio-preview.mintlify.site/docs/auth-configuration/white-labeling.md)
>
> Remove Composio branding from OAuth screens and auth flows

#### Redirecting users after authentication

You can include custom query parameters in your callback URL to carry context through the auth flow, such as identifying which user or session triggered the connection. Composio preserves your parameters and appends its own after authentication completes.

| Parameter | Description |
| - | - |
| `status` | `success` or `failed` |
| `connected_account_id` | The ID of the newly created connected account |

For example, if your callback URL is `https://your-app.com/callback?user_id=user_123`, the redirect after successful auth will be:

```text theme={null}
https://your-app.com/callback?user_id=user_123&status=success&connected_account_id=ca_abc123
```

### Direct SDK Setup

**Choose the section below that matches your toolkit's authentication method:**

#### OAuth Connections

> [!WARNING]
>
> **`initiate()` is being retired for Composio-managed OAuth.** If your auth config is Composio-managed (the default — you didn't bring your own OAuth client credentials), `initiate()` will start returning `400 BadRequest` on **2026-05-08** for new organizations and **2026-07-03** for all remaining organizations. Use [Hosted Authentication (Connect Link)](#hosted-authentication-connect-link) above with `composio.connectedAccounts.link()` (TS) / `composio.connected_accounts.link()` (Python) instead — same return shape, same `redirectUrl` / `redirect_url` field, and it works for every redirectable scheme.
>
> Custom auth configs (your own OAuth app) and non-OAuth schemes (API key, bearer token, basic) continue to work on `initiate()` unchanged. See the [migration guide](https://composio-preview.mintlify.site/docs/auth-configuration/migrating-initiate-to-link.md) and the [changelog entry](https://composio-preview.mintlify.site/docs/changelog/2026/04/24).

For OAuth flows, you'll redirect users to complete authorization. You can specify a callback URL to control where users return after authentication:

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
> from composio.types import auth_scheme
>
> composio = Composio(api_key="YOUR_COMPOSIO_API_KEY")
>
> # Use the "AUTH CONFIG ID" from your dashboard
> auth_config_id = "your_auth_config_id"
>
> # Use a unique identifier for each user in your application
> user_id = "user-1349-129-12"
>
> connection_request = composio.connected_accounts.initiate(
>   user_id=user_id,
>   auth_config_id=auth_config_id,
>   # The helper fills status="INITIALIZING"; its generated input type still requires it.
>   config=auth_scheme.oauth2({}),  # type: ignore[arg-type]
>   callback_url="https://www.yourapp.com/callback"
> )
> print(f"Redirect URL: {connection_request.redirect_url}")
>
> connected_account = connection_request.wait_for_connection()
>
> # Alternative: if you only have the connection request ID
> # connected_account = composio.connected_accounts.wait_for_connection(
> #  connection_request.id)
> # Recommended when the connection_request object is no longer available
>
> print(f"Connection established: {connected_account.id}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio, AuthScheme } from '@composio/core';
>
> const composio = new Composio({apiKey: "YOUR_COMPOSIO_API_KEY"});
>
> // Use the "AUTH CONFIG ID" from your dashboard
> const authConfigId = 'your_auth_config_id';
> // Use a unique identifier for each user in your application
> const userId = 'user-1349-129-12';
>
> const connRequest = await composio.connectedAccounts.initiate(
>   userId,
>   authConfigId,
>   {
>     config: AuthScheme.OAuth2({}),
>     callbackUrl: 'https://www.yourapp.com/callback',
>   }
> );
> console.log(`Redirect URL: ${connRequest.redirectUrl}`);
>
> const connectedAccount = await connRequest.waitForConnection();
>
> // Alternative: if you only have the connection request ID
> // const connectedAccount = await composio.connectedAccounts
> //   .waitForConnection(connRequest.id);
> // Recommended when the connRequest object is no longer available
>
> console.log(`Connection established: ${connectedAccount.id}`);
> ```

> [tab] API
>
> ```bash theme={null}
> RESPONSE=$(curl -s -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": "your_auth_config_id"}, "connection": {"user_id": "user-1349-129-12", "callback_url": "https://www.yourapp.com/callback", "state": {"authScheme": "OAUTH2", "val": {"status": "INITIALIZING"}}}}')
> echo "Redirect URL: $(echo "$RESPONSE" | jq -r '.connectionData.val.redirectUrl')"
> CONNECTED_ACCOUNT_ID=$(echo "$RESPONSE" | jq -r '.id')
>
> # After the user finishes the redirect, check the connection (poll until status is ACTIVE)
> curl -s -X GET https://backend.composio.dev/api/v3.1/connected_accounts/$CONNECTED_ACCOUNT_ID \
>   -H "x-api-key: $COMPOSIO_API_KEY" | jq '{id, status}'
> ```

> [!NOTE]
>
> When using callback URLs with `initiate()`, the appended query parameters use camelCase (`connectedAccountId`, `appName`) instead of snake\_case. See [Redirecting users after authentication](#redirecting-users-after-authentication).

#### Services with Additional Parameters

Some services like Zendesk require additional parameters such as `subdomain`:

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
> from composio.types import auth_scheme
>
> composio = Composio(api_key="your_api_key")
> user_id = "user_123"
> auth_config_id = "ac_zendesk"
>
> # For Zendesk, include the subdomain. oauth2 fills status="INITIALIZING",
> # which its generated input type incorrectly requires callers to supply.
> connection_request = composio.connected_accounts.initiate(
>   user_id=user_id,
>   auth_config_id=auth_config_id,
>   config=auth_scheme.oauth2({"subdomain": "mycompany"})  # type: ignore[arg-type]
> )
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio, AuthScheme } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const userId = 'user_123';
> const authConfigId = 'ac_zendesk';
> // For Zendesk - include subdomain
> const connRequest = await composio.connectedAccounts.initiate(userId, authConfigId, {
>   config: AuthScheme.OAuth2({
>     subdomain: 'mycompany',
>   }),
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # For Zendesk - include subdomain
> 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_zendesk"}, "connection": {"user_id": "user_123", "state": {"authScheme": "OAUTH2", "val": {"status": "INITIALIZING", "subdomain": "mycompany"}}}}'
> ```

#### API Key Connections

For API key authentication, you can either collect API keys from each user or use your own API key for all users. Popular toolkits that use API keys include Stripe, Perplexity, etc.

Here is how to initiate the flow:

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
> from composio.types import auth_scheme
>
> composio = Composio(api_key="your_api_key")
>
> # Use the "AUTH CONFIG ID" from your dashboard
> auth_config_id = "your_auth_config_id"
>
> # Use a unique identifier for each user in your application
> user_id = "user_12345678"
>
> # API key provided by the user (collected from your app's UI)
> # or use your own key
> user_api_key = "user_api_key_here"
>
> connection_request = composio.connected_accounts.initiate(
>   user_id=user_id,
>   auth_config_id=auth_config_id,
>   # The helper fills status="ACTIVE"; its generated input type still requires it.
>   config=auth_scheme.api_key({"api_key": user_api_key}),  # type: ignore[arg-type]
> )
>
> print(f"Connection established: {connection_request.id}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio, AuthScheme } from '@composio/core';
>
> const composio = new Composio({ apiKey: 'your_api_key' });
>
> // Use the "AUTH CONFIG ID" from your dashboard
> const authConfigId = 'your_auth_config_id';
> // Use a unique identifier for each user in your application
> const userId = 'user_12345678';
> // API key provided by the user (collected from your app's UI)
> // or use your own key
> const userApiKey = 'user_api_key_here';
>
> const connectionRequest = await composio.connectedAccounts.initiate(userId, authConfigId, {
>   config: AuthScheme.APIKey({
>     api_key: userApiKey,
>   }),
> });
>
> console.log(`Connection established: ${connectionRequest.id}`);
> ```

> [tab] API
>
> ```bash theme={null}
> # API key provided by the user (collected from your app's UI) or your own key
> curl -s -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": "your_auth_config_id"}, "connection": {"user_id": "user_12345678", "state": {"authScheme": "API_KEY", "val": {"status": "ACTIVE", "api_key": "user_api_key_here"}}}}' \
>   | jq -r '"Connection established: \(.id)"'
> ```

## Fetching the required config parameters for an Auth Config

When working with any toolkit, you can inspect an auth config to understand its authentication requirements and expected parameters.

Here is how you would fetch the authentication method and input fields:

> [tab] Python
>
> ```python theme={null}
> from composio import Composio
>
> composio = Composio(api_key="your_api_key")
>
> # Use the "AUTH CONFIG ID" from your dashboard
> auth_config_id = "your_auth_config_id"
>
> # Fetch the auth configuration details
> auth_config = composio.auth_configs.get(auth_config_id)
>
> # Check what authentication method this config uses
> print(f"Authentication method: {auth_config.auth_scheme}")
>
> # See what input fields are required
> print(f"Required fields: {auth_config.expected_input_fields}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
>
> const composio = new Composio({ apiKey: 'your_api_key' });
>
> // Use the "AUTH CONFIG ID" from your dashboard
> const authConfigId = 'your_auth_config_id';
>
> // Fetch the auth configuration details
> const authConfig = await composio.authConfigs.get(authConfigId);
>
> console.log(`Authentication method: ${authConfig.authScheme}`);
> console.log(`Required fields:`, authConfig.expectedInputFields);
> ```

> [tab] API
>
> ```bash theme={null}
> curl -s -X GET https://backend.composio.dev/api/v3.1/auth_configs/your_auth_config_id \
>   -H "x-api-key: $COMPOSIO_API_KEY" | jq '{auth_scheme, expected_input_fields}'
> ```

## Other Authentication Methods

Composio also supports a wide range of other auth schemas:

**Bearer Token** - Similar to API keys, provide the user's bearer token directly when creating the connection.

**Basic Auth** - Provide username and password credentials for services that use HTTP Basic Authentication.

**Custom Schemes** - Some toolkits use their own custom authentication methods. Follow the toolkit-specific requirements for such cases.

> [!NOTE]
>
> **Fetching auth config**
>
> For any of these methods, [fetch the config parameter](#fetching-the-required-config-parameters-for-an-auth-config) to determine the exact fields required. Every toolkit has its own requirements, and understanding these is essential for successfully creating connections.

Learn how to [Manage connected accounts](https://composio-preview.mintlify.site/docs/auth-configuration/connected-accounts.md) after users authenticate.

## Connection Statuses

After creating a connection, it will have one of the following statuses that indicates its current state:

| Status | What it means | What to do |
| - | - | - |
| **ACTIVE** | Connection is working. Tools can be executed. | Nothing — you're good. |
| **INITIATED** | OAuth flow started but the user hasn't completed authentication yet. Auto-expires after 10 minutes. | Redirect the user to the Connect Link to finish authentication. |
| **EXPIRED** | Credentials are no longer valid and Composio cannot refresh them automatically. See [common causes](#why-connections-expire) below. | [Subscribe to expiry events](https://composio-preview.mintlify.site/docs/authentication#connection-lifecycle) to detect this proactively, and [re-authenticate the user](https://composio-preview.mintlify.site/docs/authentication#connection-lifecycle) to refresh the connection. |
| **FAILED** | The authentication attempt did not succeed. Common causes: user denied consent during OAuth, invalid authorization code, or misconfigured auth config. | Check the `status_reason` field for details and retry the connection. |
| **INACTIVE** | Manually disabled via the API. The connection is preserved but cannot be used to execute tools. | Re-enable it via the API or dashboard to restore access. |

### Why connections expire

Composio automatically refreshes OAuth tokens before they expire. A connection is only marked as **EXPIRED** after refresh attempts have failed. Common reasons:

* **User revoked access** — The user went to the provider's settings (e.g., Google Account > Security > Third-party apps) and removed your app's access.
* **OAuth app deleted or disabled** — The OAuth application credentials were deleted or disabled in the provider's developer console.
* **Refresh token expired** — Some providers (e.g., Google with test/unverified apps) expire refresh tokens after a set period. Once expired, a new OAuth consent flow is required.
* **Provider-side revocation** — The provider revoked tokens due to policy changes, security events, or account-level restrictions.
* **Repeated transient failures** — If token refresh fails multiple times consecutively (e.g., due to prolonged provider outages), Composio marks the connection as expired after a threshold of failures.

In all cases, the user must [re-authenticate](https://composio-preview.mintlify.site/docs/authentication#connection-lifecycle) to restore the connection. Check the `status_reason` field on the connected account for the specific reason. You can also [subscribe to connection expiry events](https://composio-preview.mintlify.site/docs/authentication#connection-lifecycle) to detect this proactively.

### Waiting for Connection Establishment

The `waitForConnection` method allows you to poll for a connection to become active after initiating authentication. This is useful when you need to ensure a connection is ready before proceeding.

> [tab] Python
>
> ```python theme={null}
> # Wait for the connection to be established
> connected_account = connection_request.wait_for_connection()
> print(connected_account.id)
>
> # Alternative: Wait with custom timeout
> # connected_account = connection_request.wait_for_connection(120)  # 2 minute timeout
>
> # Alternative: If you only have the connection request ID (e.g., stored in database)
> # connection_id = connection_request.id  # You can store this ID in your database
> # connected_account = composio.connected_accounts.wait_for_connection(connection_id, 60)
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> const connectionRequest = await composio.connectedAccounts.initiate('user_123', 'ac_123', {});
> // Wait for the connection to be established
> const connectedAccount = await connectionRequest.waitForConnection();
> console.log(connectedAccount.id);
>
> // Alternative: Wait with custom timeout
> // const connectedAccount = await connectionRequest.waitForConnection(120000);  // 2 minutes
>
> // Alternative: If you only have the connection request ID (e.g., stored in database)
> // const connectionId = connectionRequest.id;  // You can store this ID in your database
> // const connectedAccount = await composio.connectedAccounts.waitForConnection(connectionId, 60000);
> ```

> [tab] API
>
> ```bash theme={null}
> # CONNECTED_ACCOUNT_ID is the ID returned when you initiated or linked the account.
> DEADLINE=$((SECONDS + 60))
> while true; do
>   ACCOUNT=$(curl --fail-with-body -s https://backend.composio.dev/api/v3.1/connected_accounts/$CONNECTED_ACCOUNT_ID \
>     -H "x-api-key: $COMPOSIO_API_KEY") || exit 1
>   STATUS=$(echo "$ACCOUNT" | jq -r '.status')
>   case "$STATUS" in
>     ACTIVE) echo "$ACCOUNT" | jq -r '.id'; break ;;
>     FAILED|EXPIRED|INACTIVE|REVOKED) echo "Connection ended: $STATUS" >&2; exit 1 ;;
>   esac
>   if [ "$SECONDS" -ge "$DEADLINE" ]; then
>     echo "Timed out waiting for authorization" >&2
>     exit 1
>   fi
>   sleep 1
> done
> ```

The method polls the Composio API, waiting 1 second between polls at first and up to 5 seconds later, until the connection:

* Becomes **ACTIVE** (returns the connected account)
* Enters a terminal state like **FAILED** or **EXPIRED** (throws an error)
* Exceeds the specified timeout (throws a timeout error)

A rate-limited poll doesn't end the wait. The method waits as long as the response asks and polls again, and these retries can carry the wait past the timeout.

### Checking Connection Status

You can check the status of a connected account programmatically:

> [tab] Python
>
> ```python theme={null}
> # Get a specific connected account
> connected_account = composio.connected_accounts.get("your_connected_account_id")
> print(f"Status: {connected_account.status}")
>
> # Filter connections by user_id, auth_config_id, and status (only active accounts)
> filtered_connections = composio.connected_accounts.list(
>     user_ids=["user_123"],
>     auth_config_ids=["your_auth_config_id"],
>     statuses=["ACTIVE"]
> )
> for connection in filtered_connections.items:
>     print(f"{connection.id}: {connection.status}")
> ```

> [tab] TypeScript
>
> ```typescript theme={null}
> import { Composio } from '@composio/core';
> const composio = new Composio({ apiKey: 'your_api_key' });
> // Get a specific connected account by its nanoid
> const connectedAccount = await composio.connectedAccounts.get('your_connected_account_id');
> console.log(`Status: ${connectedAccount.status}`);
>
> // Filter connections by user_id, auth_config_id, and status (only active accounts)
> const filteredConnections = await composio.connectedAccounts.list({
>   userIds: ['user_123'],
>   authConfigIds: ['your_auth_config_id'],
>   statuses: ['ACTIVE']
> });
> filteredConnections.items.forEach(connection => {
>   console.log(`${connection.id}: ${connection.status}`);
> });
> ```

> [tab] API
>
> ```bash theme={null}
> # Get a specific connected account
> curl -s -X GET https://backend.composio.dev/api/v3.1/connected_accounts/your_connected_account_id \
>   -H "x-api-key: $COMPOSIO_API_KEY" | jq -r '"Status: \(.status)"'
>
> # Filter connections by user_id, auth_config_id, and status (only active accounts)
> curl -s -X GET "https://backend.composio.dev/api/v3.1/connected_accounts?user_ids=user_123&auth_config_ids=your_auth_config_id&statuses=ACTIVE" \
>   -H "x-api-key: $COMPOSIO_API_KEY" | jq -r '.items[] | "\(.id): \(.status)"'
> ```

> [!NOTE]
>
> Only connections with **ACTIVE** status can be used to execute tools. If a connection is in any other state, you'll need to take appropriate action (re-authenticate, wait for processing, etc.) before using it.

## Next

> [card] [Executing tools](https://composio-preview.mintlify.site/docs/tools-direct/executing-tools.md)
>
> Run tools with providers, agentic frameworks, or direct execution
