Connected Accounts API

Manage user authentication and connected accounts

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

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

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

Filter by user

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

Filter by toolkit

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

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);

API Key auth

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);

Basic auth

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

const connection = await composio.connectedAccounts.initiate(
  'user_123',
  'auth_config_jira',
  {
    config: AuthScheme.Basic({
      username: '[e-mail]',
      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