@composio/core

@composio/core / ConnectedAccounts / ConnectedAccounts

Class: ConnectedAccounts

Defined in: ts/packages/core/src/models/ConnectedAccounts.ts:36

ConnectedAccounts class

This class is used to manage connected accounts in the Composio SDK. Connected accounts are used to authenticate with third-party services.

Constructors

Constructor

new ConnectedAccounts(client): ConnectedAccounts

Defined in: ts/packages/core/src/models/ConnectedAccounts.ts:39

Parameters

client

Composio

Returns

ConnectedAccounts

Methods

delete()

delete(nanoid): Promise<ConnectedAccountDeleteResponse>

Defined in: ts/packages/core/src/models/ConnectedAccounts.ts:268

Deletes a connected account.

This method permanently removes a connected account from the Composio platform. This action cannot be undone and will revoke any access tokens associated with the account.

Parameters

nanoid

string

The unique identifier of the connected account to delete

Returns

Promise<ConnectedAccountDeleteResponse>

The deletion response

Throws

If the account doesn’t exist or cannot be deleted

Example

1
// Delete a connected account
2
await composio.connectedAccounts.delete('conn_abc123');

disable()

disable(nanoid): Promise<ConnectedAccountUpdateStatusResponse>

Defined in: ts/packages/core/src/models/ConnectedAccounts.ts:353

Disable a connected account

Parameters

nanoid

string

Unique identifier of the connected account

Returns

Promise<ConnectedAccountUpdateStatusResponse>

Updated connected account details

Example

1
// Disable a connected account
2
const disabledAccount = await composio.connectedAccounts.disable('conn_abc123');
3
console.log(disabledAccount.isDisabled); // true
4
5
// You can also use updateStatus with a reason
6
// const disabledAccount = await composio.connectedAccounts.updateStatus('conn_abc123', {
7
//   enabled: false,
8
//   reason: 'No longer needed'
9
// });

enable()

enable(nanoid): Promise<ConnectedAccountUpdateStatusResponse>

Defined in: ts/packages/core/src/models/ConnectedAccounts.ts:331

Enable a connected account

Parameters

nanoid

string

Unique identifier of the connected account

Returns

Promise<ConnectedAccountUpdateStatusResponse>

Updated connected account details

Example

1
// Enable a previously disabled connected account
2
const enabledAccount = await composio.connectedAccounts.enable('conn_abc123');
3
console.log(enabledAccount.isDisabled); // false

get()

get(nanoid): Promise<{ }>

Defined in: ts/packages/core/src/models/ConnectedAccounts.ts:247

Retrieves a specific connected account by its ID.

This method fetches detailed information about a single connected account and transforms the response to the SDK’s standardized format.

Parameters

nanoid

string

The unique identifier of the connected account

Returns

Promise<{ }>

The connected account details

Throws

If the connected account cannot be found or an API error occurs

Example

1
// Get a connected account by ID
2
const account = await composio.connectedAccounts.get('conn_abc123');
3
console.log(account.status); // e.g., 'ACTIVE'
4
console.log(account.toolkit.slug); // e.g., 'github'

initiate()

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

Defined in: ts/packages/core/src/models/ConnectedAccounts.ts:156

Compound function to create a new connected account. This function creates a new connected account and returns a connection request. Users can then wait for the connection to be established using the waitForConnection method.

Parameters

userId

string

User ID of the connected account

authConfigId

string

Auth config ID of the connected account

options?

Options for creating a new connected account

Returns

Promise<ConnectionRequest>

Connection request object

Example

1
// For OAuth2 authentication
2
const connectionRequest = await composio.connectedAccounts.initiate(
3
  'user_123',
4
  'auth_config_123',
5
  {
6
    callbackUrl: 'https://your-app.com/callback',
7
    config: AuthScheme.OAuth2({
8
      access_token: 'your_access_token',
9
      token_type: 'Bearer'
10
    })
11
  }
12
);
13
14
// For API Key authentication
15
const connectionRequest = await composio.connectedAccounts.initiate(
16
  'user_123',
17
  'auth_config_123',
18
  {
19
    config: AuthScheme.ApiKey({
20
      api_key: 'your_api_key'
21
    })
22
  }
23
);
24
25
// For Basic authentication
26
const connectionRequest = await composio.connectedAccounts.initiate(
27
  'user_123',
28
  'auth_config_123',
29
  {
30
    config: AuthScheme.Basic({
31
      username: 'your_username',
32
      password: 'your_password'
33
    })
34
  }
35
);

Link

https://docs.composio.dev/reference/connected-accounts/create-connected-account

list()

list(query?): Promise<{ }>

Defined in: ts/packages/core/src/models/ConnectedAccounts.ts:68

Lists all connected accounts based on provided filter criteria.

This method retrieves connected accounts from the Composio API with optional filtering.

Parameters

query?

Optional query parameters for filtering connected accounts

Returns

Promise<{ }>

A paginated list of connected accounts

Throws

If the query fails validation against the expected schema

Example

1
// List all connected accounts
2
const allAccounts = await composio.connectedAccounts.list();
3
4
// List accounts for a specific user
5
const userAccounts = await composio.connectedAccounts.list({
6
  userIds: ['user123']
7
});
8
9
// List accounts for a specific toolkit
10
const githubAccounts = await composio.connectedAccounts.list({
11
  toolkitSlugs: ['github']
12
});

refresh()

refresh(nanoid): Promise<ConnectedAccountRefreshResponse>

Defined in: ts/packages/core/src/models/ConnectedAccounts.ts:288

Refreshes a connected account’s authentication credentials.

This method attempts to refresh OAuth tokens or other credentials associated with the connected account. This is useful when a token has expired or is about to expire.

Parameters

nanoid

string

The unique identifier of the connected account to refresh

Returns

Promise<ConnectedAccountRefreshResponse>

The response containing the refreshed account details

Throws

If the account doesn’t exist or credentials cannot be refreshed

Example

1
// Refresh a connected account's credentials
2
const refreshedAccount = await composio.connectedAccounts.refresh('conn_abc123');

updateStatus()

updateStatus(nanoid, params): Promise<ConnectedAccountUpdateStatusResponse>

Defined in: ts/packages/core/src/models/ConnectedAccounts.ts:312

Update the status of a connected account

Parameters

nanoid

string

Unique identifier of the connected account

params

ConnectedAccountUpdateStatusParams

Parameters for updating the status

Returns

Promise<ConnectedAccountUpdateStatusResponse>

Updated connected account details

Example

1
// Enable a connected account
2
const updatedAccount = await composio.connectedAccounts.updateStatus('conn_abc123', {
3
  enabled: true
4
});
5
6
// Disable a connected account with a reason
7
const disabledAccount = await composio.connectedAccounts.updateStatus('conn_abc123', {
8
  enabled: false,
9
  reason: 'Token expired'
10
});

waitForConnection()

waitForConnection(connectedAccountId, timeout?): Promise<{ }>

Defined in: ts/packages/core/src/models/ConnectedAccounts.ts:221

Waits for a connection request to complete and become active.

This method continuously polls the Composio API to check the status of a connection until it either becomes active, enters a terminal error state, or times out.

Parameters

connectedAccountId

string

The ID of the connected account to wait for

timeout?

number = 60000

Maximum time to wait in milliseconds (default: 60 seconds)

Returns

Promise<{ }>

The finalized connected account data

Throws

If the connected account cannot be found

Throws

If the connection enters a failed, expired, or deleted state

Throws

If the connection does not complete within the timeout period

Example

1
// Wait for a connection to complete with default timeout
2
const connectedAccount = await composio.connectedAccounts.waitForConnection('conn_123abc');
3
4
// Wait with a custom timeout of 2 minutes
5
const connectedAccount = await composio.connectedAccounts.waitForConnection('conn_123abc', 120000);