Connected Accounts API

The connectedAccounts API manages user authentication with third-party services. Each connected account represents a user’s authenticated connection to a toolkit (e.g., a user’s GitHub account).

Methods

list()

List connected accounts with optional filtering.

async list(query?: ConnectedAccountListParams): Promise<ConnectedAccountListResponse>

query

ConnectedAccountListParams

Show properties

userIds

string[]

Filter by user IDs

toolkitSlugs

string[]

Filter by toolkit slugs

authConfigIds

string[]

Filter by auth config IDs

statuses

ConnectedAccountStatus[]

Filter by status: ACTIVE, INITIATED, FAILED, etc.

cursor

string

Pagination cursor

limit

number

Maximum results

orderBy

string

Sort order

List all accounts
Filter by user
Filter by toolkit

const accounts = await composio.connectedAccounts.list();

accounts.items.forEach(account => {
  console.log(account.id, account.toolkit.slug, account.status);
});

const userAccounts = await composio.connectedAccounts.list({
  userIds: ['user_123']
});

const githubAccounts = await composio.connectedAccounts.list({
  toolkitSlugs: ['github'],
  statuses: ['ACTIVE']
});

get()

Retrieve a specific connected account by ID.

async get(nanoid: string): Promise<ConnectedAccountRetrieveResponse>

nanoid

string

required

Connected account ID

Example:

const account = await composio.connectedAccounts.get('conn_abc123');

console.log(account.status); // 'ACTIVE'
console.log(account.toolkit.slug); // 'github'
console.log(account.userId); // 'user_123'

initiate()

Create a new connected account and get a connection request.

async initiate(
  userId: string,
  authConfigId: string,
  options?: CreateConnectedAccountOptions
): Promise<ConnectionRequest>

userId

string

required

User ID to create connection for

authConfigId

string

required

Auth config to use

options

CreateConnectedAccountOptions

Show properties

callbackUrl

string

Redirect URL after OAuth completion

config

ConnectionData

Pre-fill auth credentials (for API_KEY, BASIC, etc.)

allowMultiple

boolean

default:false

Allow multiple connections per user/auth config

OAuth2 flow
API Key auth
Basic auth

const connection = await composio.connectedAccounts.initiate(
  'user_123',
  'auth_config_github',
  {
    callbackUrl: 'https://your-app.com/callback'
  }
);

// Redirect user to OAuth page
console.log(`Visit: ${connection.redirectUrl}`);

// Wait for connection to complete
const account = await connection.waitForConnection();
console.log('Connected!', account.id);

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

const connection = await composio.connectedAccounts.initiate(
  'user_123',
  'auth_config_openai',
  {
    config: AuthScheme.ApiKey({
      api_key: 'sk-...' // User's API key
    })
  }
);

const account = await connection.waitForConnection();
console.log('API key configured!', account.id);

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

const connection = await composio.connectedAccounts.initiate(
  'user_123',
  'auth_config_jira',
  {
    config: AuthScheme.Basic({
      username: '[email protected]',
      password: 'password123'
    })
  }
);

link()

Create a Composio Connect link for a user to connect their account.

async link(
  userId: string,
  authConfigId: string,
  options?: CreateConnectedAccountLinkOptions
): Promise<ConnectionRequest>

userId

string

required

User ID

authConfigId

string

required

Auth config ID

options.callbackUrl

string

Redirect URL after connection

Example:

const link = await composio.connectedAccounts.link(
  'user_123',
  'auth_config_github',
  { callbackUrl: 'https://your-app.com/callback' }
);

console.log(`Send user to: ${link.redirectUrl}`);

// Wait for connection
const account = await link.waitForConnection();

waitForConnection()

Wait for a connection to become active.

async waitForConnection(
  connectedAccountId: string,
  timeout?: number
): Promise<ConnectedAccountRetrieveResponse>

connectedAccountId

string

required

Connected account ID to wait for

timeout

number

default:60000

Maximum wait time in milliseconds

Example:

try {
  const account = await composio.connectedAccounts.waitForConnection(
    'conn_abc123',
    120000 // 2 minutes
  );
  console.log('Connection active!', account.id);
} catch (error) {
  console.error('Connection timed out or failed');
}

delete()

Delete a connected account.

async delete(nanoid: string): Promise<ConnectedAccountDeleteResponse>

nanoid

string

required

Connected account ID

Example:

await composio.connectedAccounts.delete('conn_abc123');
console.log('Account deleted');

refresh()

Refresh a connected account’s credentials.

async refresh(
  nanoid: string,
  options?: ConnectedAccountRefreshOptions
): Promise<ConnectedAccountRefreshResponse>

nanoid

string

required

Connected account ID

options

ConnectedAccountRefreshOptions

Show properties

redirectUrl

string

Redirect URL if re-auth needed

validateCredentials

boolean

Validate credentials after refresh

Example:

const refreshed = await composio.connectedAccounts.refresh('conn_abc123', {
  validateCredentials: true
});

console.log('Refreshed:', refreshed);

enable() / disable()

Enable or disable a connected account.

async enable(nanoid: string): Promise<ConnectedAccountUpdateStatusResponse>
async disable(nanoid: string): Promise<ConnectedAccountUpdateStatusResponse>

Example:

// Temporarily disable an account
await composio.connectedAccounts.disable('conn_abc123');

// Re-enable it later
await composio.connectedAccounts.enable('conn_abc123');

updateStatus()

Update connected account status with a reason.

async updateStatus(
  nanoid: string,
  params: ConnectedAccountUpdateStatusParams
): Promise<ConnectedAccountUpdateStatusResponse>

Example:

await composio.connectedAccounts.updateStatus('conn_abc123', {
  enabled: false,
  reason: 'Token expired, needs re-authentication'
});

Types

ConnectedAccountRetrieveResponse

interface ConnectedAccountRetrieveResponse {
  id: string; // Account ID
  uuid: string; // UUID
  userId: string; // External user ID
  toolkit: { // Associated toolkit
    slug: string;
    name: string;
  };
  authConfig: { // Auth config used
    id: string;
    mode: AuthSchemeType;
  };
  status: ConnectedAccountStatus; // ACTIVE, INITIATED, etc.
  isDisabled: boolean; // Disabled status
  createdAt: string; // ISO timestamp
  updatedAt: string; // ISO timestamp
  state?: ConnectionData; // Auth state (credentials)
}

ConnectedAccountStatus

type ConnectedAccountStatus =
  | 'INITIATED' // Connection started
  | 'ACTIVE' // Successfully connected
  | 'FAILED' // Connection failed
  | 'EXPIRED' // Credentials expired
  | 'DELETED'; // Account deleted

ConnectionRequest

interface ConnectionRequest {
  id: string; // Connected account ID
  status: ConnectedAccountStatus;
  redirectUrl: string | null; // OAuth redirect URL
  waitForConnection(timeout?: number): Promise<ConnectedAccountRetrieveResponse>;
}

Next Steps

Auth Configs

Configure authentication methods

Tools API

Execute tools with connections

Toolkits

Browse available toolkits

Triggers

Set up webhooks

Overview

Core API

Providers

Advanced

Connected Accounts API

Methods

list()

get()

initiate()

link()

waitForConnection()

delete()

refresh()

enable() / disable()

updateStatus()

Types

ConnectedAccountRetrieveResponse

ConnectedAccountStatus

ConnectionRequest

Next Steps

Auth Configs

Tools API

Toolkits

Triggers

Build docs developers (and LLMs) love

Overview

Core API

Providers

Advanced

​Methods

​list()

​get()

​initiate()

​link()

​waitForConnection()

​delete()

​refresh()

​enable() / disable()

​updateStatus()

​Types

​ConnectedAccountRetrieveResponse

​ConnectedAccountStatus

​ConnectionRequest

​Next Steps

Auth Configs

Tools API

Toolkits

Triggers

Build docs developers (and LLMs) love

Methods

list()

get()

initiate()

link()

waitForConnection()

delete()

refresh()

enable() / disable()

updateStatus()

Types

ConnectedAccountRetrieveResponse

ConnectedAccountStatus

ConnectionRequest

Next Steps