ConnectedAccounts

Usage

Access this class through the composio.connectedAccounts property:

const composio = new Composio({ apiKey: 'your-api-key' });
const result = await composio.connectedAccounts.list();

Methods

completeAuth()

Complete a deferred OAuth connection once you have verified the user's identity.

When your project has an OAuth callback verifier configured, Composio does not activate a new OAuth connection by itself: it redirects to your verifier with a single-use session URI. After confirming who the user is, redeem that session URI here; Composio checks that your project owns the pending connection and that userId is its owner, completes the token exchange, and the connection becomes ACTIVE.

The session URI is single-use: redeeming it twice, or after it expires, fails with a 404 from the API.

async completeAuth(params: { sessionUri: string; userId: string }, requestOptions?: ComposioRequestOptions): Promise<{ connectedAccountId: string; toolkitSlug: string }>

Parameters

Name	Type	Description
`params`	`\{ sessionUri: string; userId: string \}`	`userId` the connection was initiated for and the verifier's `sessionUri`
`requestOptions?`	`ComposioRequestOptions`

Returns

Promise<\{ connectedAccountId: string; toolkitSlug: string \}> — The completed connection's ID and toolkit

Example

// In your verifier route, after authenticating the user:
const { connectedAccountId, toolkitSlug } = await composio.connectedAccounts.completeAuth({
  userId: 'user_123',
  sessionUri, // the session URI from the verifier redirect
});

delete()

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.

async delete(nanoid: string, requestOptions?: ComposioRequestOptions): Promise<ConnectedAccountDeleteResponse>

Parameters

Name	Type	Description
`nanoid`	`string`	The unique identifier of the connected account to delete
`requestOptions?`	`ComposioRequestOptions`

Returns

Promise<ConnectedAccountDeleteResponse> — The deletion response

Example

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

disable()

Disable a connected account

async disable(nanoid: string, requestOptions?: ComposioRequestOptions): Promise<ConnectedAccountUpdateStatusResponse>

Parameters

Name	Type	Description
`nanoid`	`string`	Unique identifier of the connected account
`requestOptions?`	`ComposioRequestOptions`

Returns

Promise<ConnectedAccountUpdateStatusResponse> — Updated connected account details

Example

// Disable a connected account
const disabledAccount = await composio.connectedAccounts.disable('conn_abc123');
console.log(disabledAccount.isDisabled); // true

// You can also use updateStatus with a reason
// const disabledAccount = await composio.connectedAccounts.updateStatus('conn_abc123', {
//   enabled: false,
//   reason: 'No longer needed'
// });

enable()

Enable a connected account

async enable(nanoid: string, requestOptions?: ComposioRequestOptions): Promise<ConnectedAccountUpdateStatusResponse>

Parameters

Name	Type	Description
`nanoid`	`string`	Unique identifier of the connected account
`requestOptions?`	`ComposioRequestOptions`

Returns

Promise<ConnectedAccountUpdateStatusResponse> — Updated connected account details

Example

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

get()

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.

async get(nanoid: string, requestOptions?: ComposioRequestOptions): Promise<{ alias?: string | null; authConfig: { authScheme?: 'OAUTH2' | 'OAUTH1' | 'API_KEY' | 'BASIC' | 'BILLCOM_AUTH' | 'BEARER_TOKEN' | 'GOOGLE_SERVICE_ACCOUNT' | 'NO_AUTH' | 'BASIC_WITH_JWT' | 'CALCOM_AUTH' | 'SERVICE_ACCOUNT' | 'SAML' | 'DCR_OAUTH' | 'CIMD_OAUTH' | 'S2S_OAUTH2'; id: string; isComposioManaged: boolean; isDisabled: boolean }; createdAt: string; data?: Record<string, unknown>; experimental?: { accountType?: 'PRIVATE' | 'SHARED'; aclConfigForShared?: { allowAllUsers: boolean; allowedUserIds: string[]; notAllowedUserIds: string[] } }; id: string; isDisabled: boolean; params?: Record<string, unknown>; state?: { authScheme: 'OAUTH1'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'OAUTH2'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'S2S_OAUTH2'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'API_KEY'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BASIC'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BEARER_TOKEN'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'GOOGLE_SERVICE_ACCOUNT'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'NO_AUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'CALCOM_AUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BILLCOM_AUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BASIC_WITH_JWT'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'SERVICE_ACCOUNT'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'SAML'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'DCR_OAUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> }; status: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED' | 'INACTIVE' | 'REVOKED'; statusReason: string | null; testRequestEndpoint?: string; toolkit: { slug: string }; updatedAt: string; wordId?: string | null }>

Parameters

Name	Type	Description
`nanoid`	`string`	The unique identifier of the connected account
`requestOptions?`	`ComposioRequestOptions`

Returns

Promise<\{ alias?: string \| null; authConfig: \{ authScheme?: 'OAUTH2' \| 'OAUTH1' \| 'API_KEY' \| 'BASIC' \| 'BILLCOM_AUTH' \| 'BEARER_TOKEN' \| 'GOOGLE_SERVICE_ACCOUNT' \| 'NO_AUTH' \| 'BASIC_WITH_JWT' \| 'CALCOM_AUTH' \| 'SERVICE_ACCOUNT' \| 'SAML' \| 'DCR_OAUTH' \| 'CIMD_OAUTH' \| 'S2S_OAUTH2'; id: string; isComposioManaged: boolean; isDisabled: boolean \}; createdAt: string; data?: Record<string, unknown>; experimental?: \{ accountType?: 'PRIVATE' \| 'SHARED'; aclConfigForShared?: \{ allowAllUsers: boolean; allowedUserIds: string[]; notAllowedUserIds: string[] \} \}; id: string; isDisabled: boolean; params?: Record<string, unknown>; state?: \{ authScheme: 'OAUTH1'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'OAUTH2'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'S2S_OAUTH2'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'API_KEY'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'BASIC'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'BEARER_TOKEN'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'GOOGLE_SERVICE_ACCOUNT'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'NO_AUTH'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'CALCOM_AUTH'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'BILLCOM_AUTH'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'BASIC_WITH_JWT'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'SERVICE_ACCOUNT'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'SAML'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \} \| \{ authScheme: 'DCR_OAUTH'; val: objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \| objectOutputType<..., ..., ...> \}; status: 'INITIALIZING' \| 'INITIATED' \| 'ACTIVE' \| 'FAILED' \| 'EXPIRED' \| 'INACTIVE' \| 'REVOKED'; statusReason: string \| null; testRequestEndpoint?: string; toolkit: \{ slug: string \}; updatedAt: string; wordId?: string \| null \}> — The connected account details

Example

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

initiate()

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.

Deprecated for Composio-managed OAuth (OAuth1, OAuth2, DCR_OAUTH). The legacy POST /api/v3/connected_accounts endpoint that this method wraps is being retired for Composio-managed auth configs on redirectable schemes. The cutover is 2026-05-08 for new organizations and 2026-07-03 for all remaining organizations. After your org's cutover, this method will throw ComposioLegacyConnectedAccountsEndpointRetiredError for that specific combination.

Use ConnectedAccounts.link for Composio-managed OAuth — it works for every redirectable scheme regardless of whether the auth config is Composio-managed or custom, and the return shape is the same.

Custom auth configs (your own OAuth app) and non-OAuth schemes (API key, bearer token, basic auth) are unaffected and continue to work on initiate(). See https://docs.composio.dev/docs/changelog/2026/04/24

async initiate(userId: string, authConfigId: string, options?: { alias?: string; allowMultiple?: boolean; callbackUrl?: string; config?: { authScheme: 'OAUTH1'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'OAUTH2'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'S2S_OAUTH2'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'API_KEY'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'BASIC'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'BEARER_TOKEN'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'GOOGLE_SERVICE_ACCOUNT'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'NO_AUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'CALCOM_AUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'BILLCOM_AUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'BASIC_WITH_JWT'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'SERVICE_ACCOUNT'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'SAML'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } | { authScheme: 'DCR_OAUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> | objectOutputType<... & ..., ZodUnknown, 'strip'> } }, requestOptions?: ComposioRequestOptions): Promise<ConnectionRequest>

Parameters

Name	Type	Description
`userId`	`string`	User ID of the connected account
`authConfigId`	`string`	Auth config ID of the connected account
`options?`	\{ alias?: string; allowMultiple?: boolean; callbackUrl?: string; config?: \{ authScheme: 'OAUTH1'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'OAUTH2'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'S2S_OAUTH2'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'API_KEY'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'BASIC'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'BEARER_TOKEN'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'GOOGLE_SERVICE_ACCOUNT'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'NO_AUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'CALCOM_AUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'BILLCOM_AUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'BASIC_WITH_JWT'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'SERVICE_ACCOUNT'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'SAML'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \| \{ authScheme: 'DCR_OAUTH'; val: objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \| objectOutputType<... & ..., ZodUnknown, 'strip'> \} \}	Options for creating a new connected account
`requestOptions?`	`ComposioRequestOptions`

Returns

Promise<ConnectionRequest> — Connection request object

Example

// For OAuth2 authentication
const connectionRequest = await composio.connectedAccounts.initiate(
  'user_123',
  'auth_config_123',
  {
    callbackUrl: 'https://your-app.com/callback',
    config: AuthScheme.OAuth2({
      access_token: 'your_access_token',
      token_type: 'Bearer'
    })
  }
);

// For API Key authentication
const connectionRequest = await composio.connectedAccounts.initiate(
  'user_123',
  'auth_config_123',
  {
    config: AuthScheme.ApiKey({
      api_key: 'your_api_key'
    })
  }
);

// For Basic authentication
const connectionRequest = await composio.connectedAccounts.initiate(
  'user_123',
  'auth_config_123',
  {
    config: AuthScheme.Basic({
      username: 'your_username',
      password: 'your_password'
    })
  }
);

link()

async link(userId: string, authConfigId: string, options?: { alias?: string; allowMultiple?: boolean; callbackUrl?: string; experimental?: { accountType?: 'PRIVATE' | 'SHARED'; aclConfigForShared?: { allowAllUsers?: boolean; allowedUserIds?: string[]; notAllowedUserIds?: string[] } } }, requestOptions?: ComposioRequestOptions): Promise<ConnectionRequest>

Parameters

Name	Type	Description
`userId`	`string`	{string} - The external user ID to create the connected account for.
`authConfigId`	`string`	{string} - The auth config ID to create the connected account for.
`options?`	`\{ alias?: string; allowMultiple?: boolean; callbackUrl?: string; experimental?: \{ accountType?: 'PRIVATE' \| 'SHARED'; aclConfigForShared?: \{ allowAllUsers?: boolean; allowedUserIds?: string[]; notAllowedUserIds?: string[] \} \} \}`	{CreateConnectedAccountLinkOptions} - Options for creating a new connected account link.
`requestOptions?`	`ComposioRequestOptions`

Returns

Promise<ConnectionRequest> — Connection request object

Example

// create a connection request and redirect the user to the redirect url
const connectionRequest = await composio.connectedAccounts.link('user_123', 'auth_config_123');
const redirectUrl = connectionRequest.redirectUrl;
console.log(`Visit: ${redirectUrl} to authenticate your account`);

// Wait for the connection to be established
const connectedAccount = await connectionRequest.waitForConnection()

// create a connection request and redirect the user to the redirect url
const connectionRequest = await composio.connectedAccounts.link('user_123', 'auth_config_123', {
  callbackUrl: 'https://your-app.com/callback'
});
const redirectUrl = connectionRequest.redirectUrl;
console.log(`Visit: ${redirectUrl} to authenticate your account`);

// Wait for the connection to be established
const connectedAccount = await composio.connectedAccounts.waitForConnection(connectionRequest.id);

list()

Lists all connected accounts based on provided filter criteria.

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

async list(query?: { accountType?: 'PRIVATE' | 'SHARED' | 'ALL'; authConfigIds?: string[] | null; cursor?: string | null; limit?: number | null; orderBy?: 'created_at' | 'updated_at'; statuses?: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED' | 'INACTIVE' | 'REVOKED'[] | null; toolkitSlugs?: string[] | null; userIds?: string[] | null }, requestOptions?: ComposioRequestOptions): Promise<{ items: { alias?: string | null; authConfig: { authScheme?: ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ... | ...; id: string; isComposioManaged: boolean; isDisabled: boolean }; createdAt: string; data?: Record<string, unknown>; experimental?: { accountType?: ... | ...; aclConfigForShared?: { allowAllUsers: ...; allowedUserIds: ...; notAllowedUserIds: ... } }; id: string; isDisabled: boolean; params?: Record<string, unknown>; state?: { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... } | { authScheme: ...; val: ... }; status: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED' | 'INACTIVE' | 'REVOKED'; statusReason: string | null; testRequestEndpoint?: string; toolkit: { slug: string }; updatedAt: string; wordId?: string | null }[]; nextCursor?: string | null; totalPages: number }>

Parameters

Name	Type	Description
`query?`	`\{ accountType?: 'PRIVATE' \| 'SHARED' \| 'ALL'; authConfigIds?: string[] \| null; cursor?: string \| null; limit?: number \| null; orderBy?: 'created_at' \| 'updated_at'; statuses?: 'INITIALIZING' \| 'INITIATED' \| 'ACTIVE' \| 'FAILED' \| 'EXPIRED' \| 'INACTIVE' \| 'REVOKED'[] \| null; toolkitSlugs?: string[] \| null; userIds?: string[] \| null \}`	Optional query parameters for filtering connected accounts
`requestOptions?`	`ComposioRequestOptions`

Returns

Promise<\{ items: \{ alias?: string \| null; authConfig: \{ authScheme?: ... \| ... \| ... \| ... \| ... \| ... \| ... \| ... \| ... \| ... \| ... \| ... \| ... \| ... \| ...; id: string; isComposioManaged: boolean; isDisabled: boolean \}; createdAt: string; data?: Record<string, unknown>; experimental?: \{ accountType?: ... \| ...; aclConfigForShared?: \{ allowAllUsers: ...; allowedUserIds: ...; notAllowedUserIds: ... \} \}; id: string; isDisabled: boolean; params?: Record<string, unknown>; state?: \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \} \| \{ authScheme: ...; val: ... \}; status: 'INITIALIZING' \| 'INITIATED' \| 'ACTIVE' \| 'FAILED' \| 'EXPIRED' \| 'INACTIVE' \| 'REVOKED'; statusReason: string \| null; testRequestEndpoint?: string; toolkit: \{ slug: string \}; updatedAt: string; wordId?: string \| null \}[]; nextCursor?: string \| null; totalPages: number \}> — A paginated list of connected accounts

Example

// List all connected accounts
const allAccounts = await composio.connectedAccounts.list();

// List accounts for a specific user
const userAccounts = await composio.connectedAccounts.list({
  userIds: ['user123']
});

// List accounts for a specific toolkit
const githubAccounts = await composio.connectedAccounts.list({
  toolkitSlugs: ['github']
});

refresh() (deprecated)

Deprecated

The POST /connected_accounts/\{id\}/refresh endpoint is deprecated by the Composio API. Re-initiate authentication instead: composio.connectedAccounts.link(userId, authConfigId) for a fresh connection, or session.authorize(toolkit) from a session. Behaviour is unchanged while the endpoint remains available; do not generate new code against refresh.

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.

async refresh(nanoid: string, options?: { redirectUrl?: string; validateCredentials?: boolean }, requestOptions?: ComposioRequestOptions): Promise<ConnectedAccountRefreshResponse>

Parameters

Name	Type	Description
`nanoid`	`string`	The unique identifier of the connected account to refresh
`options?`	`\{ redirectUrl?: string; validateCredentials?: boolean \}`
`requestOptions?`	`ComposioRequestOptions`

Returns

Promise<ConnectedAccountRefreshResponse> — The response containing the refreshed account details

Example

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

revoke()

Revoke a connected account at the upstream provider.

Best-effort upstream revocation of the stored tokens/credentials; on success the connection status becomes REVOKED. Revoking an already revoked connection returns an empty revokedTokens list without an upstream call.

async revoke(nanoid: string, requestOptions?: ComposioRequestOptions): Promise<{ connectedAccount: { id: string; status: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED' | 'INACTIVE' | 'REVOKED' }; revokedTokens: 'access_token' | 'refresh_token' | 'credential'[] }>

Parameters

Name	Type	Description
`nanoid`	`string`	The unique identifier of the connected account to revoke
`requestOptions?`	`ComposioRequestOptions`

Returns

Promise<\{ connectedAccount: \{ id: string; status: 'INITIALIZING' \| 'INITIATED' \| 'ACTIVE' \| 'FAILED' \| 'EXPIRED' \| 'INACTIVE' \| 'REVOKED' \}; revokedTokens: 'access_token' \| 'refresh_token' \| 'credential'[] \}> — Which tokens were revoked and the resulting status

Example

const result = await composio.connectedAccounts.revoke('conn_abc123');
console.log(result.connectedAccount.status); // 'REVOKED'
console.log(result.revokedTokens); // e.g. ['access_token', 'refresh_token']

update()

Enable or disable a connected account. Accepts { enabled: boolean }.

Use updateAcl() for ACL writes on SHARED connections.

async update(nanoid: string, params: ConnectedAccountUpdateStatusParams, requestOptions?: ComposioRequestOptions): Promise<ConnectedAccountUpdateStatusResponse>

Parameters

Name	Type	Description
`nanoid`	`string`	The unique identifier of the connected account
`params`	`ConnectedAccountUpdateStatusParams`	The update parameters
`requestOptions?`	`ComposioRequestOptions`

Returns

Promise<ConnectedAccountUpdateStatusResponse> — The update response

Example

// Disable an account
await composio.connectedAccounts.update('ca_abc123', { enabled: false });

updateAcl()

Update the per-user ACL on a SHARED connected account. Experimental — shape may change in future releases.

Only meaningful for SHARED connections — calling this on a PRIVATE connection raises ComposioAclOnlyForSharedError (400). ACL writes require the connection's creator or an API key.

PATCH semantics: omit a field to leave it unchanged; pass an empty array to clear an allow/deny list. At least one field must be provided.

async updateAcl(nanoid: string, params: { allowAllUsers?: boolean; allowedUserIds?: string[]; notAllowedUserIds?: string[] }): Promise<ConnectedAccountPatchResponse>

Parameters

Name	Type	Description
`nanoid`	`string`	The unique identifier of the connected account
`params`	`\{ allowAllUsers?: boolean; allowedUserIds?: string[]; notAllowedUserIds?: string[] \}`	The ACL fields to patch

Returns

Promise<ConnectedAccountPatchResponse> — The PATCH response

Example

// Allow every userId to use this SHARED connection
await composio.connectedAccounts.updateAcl('ca_abc123', { allowAllUsers: true });

// Targeted allow list
await composio.connectedAccounts.updateAcl('ca_abc123', {
  allowedUserIds: ['user_alice', 'user_bob'],
});

// Clear the allow list (back to deny-by-default unless allowAllUsers is true)
await composio.connectedAccounts.updateAcl('ca_abc123', { allowedUserIds: [] });

updateStatus()

Update the status of a connected account

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

Parameters

Name	Type	Description
`nanoid`	`string`	Unique identifier of the connected account
`params`	`ConnectedAccountUpdateStatusParams`	Parameters for updating the status
`requestOptions?`	`ComposioRequestOptions`

Returns

Promise<ConnectedAccountUpdateStatusResponse> — Updated connected account details

Example

// Enable a connected account
const updatedAccount = await composio.connectedAccounts.updateStatus('conn_abc123', {
  enabled: true
});

// Disable a connected account with a reason
const disabledAccount = await composio.connectedAccounts.updateStatus('conn_abc123', {
  enabled: false,
  reason: 'Token expired'
});

waitForConnection()

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.

async waitForConnection(connectedAccountId: string, timeout?: number): Promise<{ alias?: string | null; authConfig: { authScheme?: 'OAUTH2' | 'OAUTH1' | 'API_KEY' | 'BASIC' | 'BILLCOM_AUTH' | 'BEARER_TOKEN' | 'GOOGLE_SERVICE_ACCOUNT' | 'NO_AUTH' | 'BASIC_WITH_JWT' | 'CALCOM_AUTH' | 'SERVICE_ACCOUNT' | 'SAML' | 'DCR_OAUTH' | 'CIMD_OAUTH' | 'S2S_OAUTH2'; id: string; isComposioManaged: boolean; isDisabled: boolean }; createdAt: string; data?: Record<string, unknown>; experimental?: { accountType?: 'PRIVATE' | 'SHARED'; aclConfigForShared?: { allowAllUsers: boolean; allowedUserIds: string[]; notAllowedUserIds: string[] } }; id: string; isDisabled: boolean; params?: Record<string, unknown>; state?: { authScheme: 'OAUTH1'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'OAUTH2'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'S2S_OAUTH2'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'API_KEY'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BASIC'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BEARER_TOKEN'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'GOOGLE_SERVICE_ACCOUNT'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'NO_AUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'CALCOM_AUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BILLCOM_AUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'BASIC_WITH_JWT'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'SERVICE_ACCOUNT'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'SAML'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> } | { authScheme: 'DCR_OAUTH'; val: objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> | objectOutputType<..., ..., ...> }; status: 'INITIALIZING' | 'INITIATED' | 'ACTIVE' | 'FAILED' | 'EXPIRED' | 'INACTIVE' | 'REVOKED'; statusReason: string | null; testRequestEndpoint?: string; toolkit: { slug: string }; updatedAt: string; wordId?: string | null }>

Parameters

Name	Type	Description
`connectedAccountId`	`string`	The ID of the connected account to wait for
`timeout?`	`number`	Maximum time to wait in milliseconds (default: 60 seconds)

Returns

Example

// Wait for a connection to complete with default timeout
const connectedAccount = await composio.connectedAccounts.waitForConnection('conn_123abc');

// Wait with a custom timeout of 2 minutes
const connectedAccount = await composio.connectedAccounts.waitForConnection('conn_123abc', 120000);

Edit this page on GitHub

ConnectedAccounts

On this page