ConnectedAccounts API — TypeScript SDK Reference

The ConnectedAccounts class manages authenticated connections between your users and external services. A connected account stores the OAuth tokens, API keys, or other credentials that Composio needs to execute tools on a user’s behalf. Each connected account belongs to a user ID and an auth config, and has a status that reflects the current authentication state.

connectedAccounts.link()

Create a Composio Connect Link — the recommended way to start an OAuth flow for Composio-managed auth configs. Returns a ConnectionRequest with a redirectUrl to send the user to.

composio.connectedAccounts.link(
  userId: string,
  authConfigId: string,
  options?: CreateConnectedAccountLinkOptions
): Promise<ConnectionRequest>

userId

string

required

External user identifier from your database.

authConfigId

string

required

Auth config ID to connect. Obtain this from composio.authConfigs.list() or the Composio dashboard.

options.callbackUrl

string

URL to redirect the user to after they complete the OAuth flow. Your server receives ?status=success or ?status=failed as a query parameter.

options.alias

string

Human-readable alias for this connection. Must be unique per userId and toolkit within your project.

options.allowMultiple

boolean

Allow creating multiple connections for the same user and auth config. When false (default), throws ComposioMultipleConnectedAccountsError if an active connection already exists.

ConnectionRequest

string

Connected account ID. Use this to poll for connection status.

status

string

Current status — one of INITIALIZING, INITIATED, ACTIVE, FAILED, EXPIRED, INACTIVE, or REVOKED.

redirectUrl

string | null

URL to redirect the user to for OAuth flows. null for non-redirectable auth schemes (API key, basic auth).

waitForConnection

function

Polls until the connection status becomes ACTIVE or a terminal error state. See below.

connectedAccounts.initiate()

Create a connected account directly. Use this for non-OAuth auth schemes (API key, bearer token, basic auth) or custom OAuth apps. For Composio-managed OAuth, prefer link().

The initiate() method is deprecated for Composio-managed OAuth auth configs (OAuth2, OAuth1, DCR_OAUTH). Composio is retiring the underlying endpoint. Use link() for all new OAuth integrations.

composio.connectedAccounts.initiate(
  userId: string,
  authConfigId: string,
  options?: CreateConnectedAccountOptions
): Promise<ConnectionRequest>

userId

string

required

External user identifier.

authConfigId

string

required

Auth config ID to connect.

options.callbackUrl

string

OAuth callback URL.

options.config

ConnectionData

Pre-populated authentication credentials. Use with API key, bearer token, or basic auth configs to provide credentials at creation time without a redirect flow.

options.alias

string

Human-readable alias for this connection.

options.allowMultiple

boolean

Allow multiple connections per user per auth config. Defaults to false.

connectedAccounts.waitForConnection()

Poll until a connected account reaches ACTIVE status or a terminal error state. Throws on timeout or failure.

composio.connectedAccounts.waitForConnection(
  connectedAccountId: string,
  timeout?: number
): Promise<ConnectedAccountRetrieveResponse>

connectedAccountId

string

required

ID of the connected account to poll.

timeout

number

Maximum time to wait in milliseconds. Defaults to 60000 (60 seconds).

connectedAccounts.get()

Retrieve a connected account by its ID.

composio.connectedAccounts.get(nanoid: string): Promise<ConnectedAccountRetrieveResponse>

ConnectedAccountRetrieveResponse

string

Unique connected account identifier.

status

string

One of INITIALIZING, INITIATED, ACTIVE, FAILED, EXPIRED, INACTIVE, REVOKED.

toolkit

{ slug: string }

The toolkit this connection belongs to.

authConfig

object

Auth config metadata including id, authScheme, isComposioManaged, and isDisabled.

state

ConnectionData

The connection’s auth state (tokens, API keys, etc.).

isDisabled

boolean

Whether this connection has been manually disabled.

createdAt

string

ISO 8601 creation timestamp.

updatedAt

string

ISO 8601 last-updated timestamp.

connectedAccounts.list()

List connected accounts with optional filtering.

composio.connectedAccounts.list(
  query?: ConnectedAccountListParams
): Promise<ConnectedAccountListResponse>

query.userIds

string[]

Filter by user IDs.

query.toolkitSlugs

string[]

Filter by toolkit slugs (e.g. ['github']).

query.authConfigIds

string[]

Filter by auth config IDs.

query.statuses

string[]

Filter by status values. Valid values: INITIALIZING, INITIATED, ACTIVE, FAILED, EXPIRED, INACTIVE, REVOKED.

query.cursor

string

Pagination cursor from a previous response.

query.limit

number

Maximum number of results per page.

query.orderBy

string

Sort field — 'created_at' or 'updated_at'.

ConnectedAccountListResponse

items

ConnectedAccountRetrieveResponse[]

Connected accounts for the current page.

nextCursor

string | null

Cursor for the next page. null when there are no more results.

totalPages

number

Total number of pages.

connectedAccounts.delete()

Permanently delete a connected account. This action cannot be undone and revokes any associated access tokens.

composio.connectedAccounts.delete(nanoid: string): Promise<ConnectedAccountDeleteResponse>

connectedAccounts.refresh()

Force a token refresh for a connected account. Useful when an OAuth token has expired or is about to expire.

composio.connectedAccounts.refresh(
  nanoid: string,
  options?: ConnectedAccountRefreshOptions
): Promise<ConnectedAccountRefreshResponse>

options.redirectUrl

string

Redirect URL for re-authentication flows where the token cannot be refreshed silently.

options.validateCredentials

boolean

Validate the refreshed credentials against the upstream API before returning.

connectedAccounts.update()

Enable or disable a connected account. Accepts { enabled: boolean }. A lower-level alternative to enable() / disable() when you want to pass the flag programmatically.

composio.connectedAccounts.update(
  nanoid: string,
  params: { enabled: boolean }
): Promise<ConnectedAccountUpdateStatusResponse>

nanoid

string

required

Unique identifier of the connected account.

params.enabled

boolean

required

true to enable the account, false to disable it.

connectedAccounts.enable() / disable()

Enable or disable a connected account without deleting it.

composio.connectedAccounts.enable(nanoid: string): Promise<ConnectedAccountUpdateStatusResponse>
composio.connectedAccounts.disable(nanoid: string): Promise<ConnectedAccountUpdateStatusResponse>

Examples

OAuth flow with link()
API key auth (no redirect)
List active connections

import { Composio } from '@composio/core';

const composio = new Composio();

// 1. Create an auth config (or use an existing one from the dashboard)
const authConfig = await composio.authConfigs.create('github', {
  type: 'use_composio_managed_auth',
  name: 'GitHub OAuth',
});

// 2. Initiate the connection — get a redirect URL
const connectionRequest = await composio.connectedAccounts.link(
  'user_123',
  authConfig.id,
  { callbackUrl: 'https://your-app.com/auth/callback' }
);

console.log('Send the user to:', connectionRequest.redirectUrl);

// 3. After the user completes OAuth, wait for ACTIVE status
const account = await composio.connectedAccounts.waitForConnection(
  connectionRequest.id,
  120_000 // 2-minute timeout
);

console.log('Connected!', account.id, account.status);

import { Composio } from '@composio/core';

const composio = new Composio();

// Provide API key credentials directly — no OAuth redirect needed
const connectionRequest = await composio.connectedAccounts.initiate(
  'user_123',
  'your-api-key-auth-config-id',
  {
    config: {
      val: {
        authScheme: 'API_KEY',
        apiKey: 'user-provided-api-key',
      },
    },
  }
);

// For API key auth the account is ACTIVE immediately
const account = await connectionRequest.waitForConnection();
console.log('Account status:', account.status); // ACTIVE

import { Composio } from '@composio/core';

const composio = new Composio();

const { items } = await composio.connectedAccounts.list({
  userIds: ['user_123'],
  statuses: ['ACTIVE'],
});

items.forEach(account => {
  console.log(`${account.toolkit.slug}: ${account.id} (${account.status})`);
});

TypeScript SDK

Python SDK

REST API

ConnectedAccounts API — TypeScript SDK Reference

connectedAccounts.link()

ConnectionRequest

connectedAccounts.initiate()

connectedAccounts.waitForConnection()

connectedAccounts.get()

ConnectedAccountRetrieveResponse

connectedAccounts.list()

ConnectedAccountListResponse

connectedAccounts.delete()

connectedAccounts.refresh()

connectedAccounts.update()

connectedAccounts.enable() / disable()

Examples

Build docs developers (and LLMs) love

TypeScript SDK

Python SDK

REST API

Documentation Index

​connectedAccounts.link()

​ConnectionRequest

​connectedAccounts.initiate()

​connectedAccounts.waitForConnection()

​connectedAccounts.get()

​ConnectedAccountRetrieveResponse

​connectedAccounts.list()

​ConnectedAccountListResponse

​connectedAccounts.delete()

​connectedAccounts.refresh()

​connectedAccounts.update()

​connectedAccounts.enable() / disable()

​Examples

Build docs developers (and LLMs) love

connectedAccounts.link()

ConnectionRequest

connectedAccounts.initiate()

connectedAccounts.waitForConnection()

connectedAccounts.get()

ConnectedAccountRetrieveResponse

connectedAccounts.list()

ConnectedAccountListResponse

connectedAccounts.delete()

connectedAccounts.refresh()

connectedAccounts.update()

connectedAccounts.enable() / disable()

Examples