Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
/**
* @fileoverview Auth configs class for Composio SDK, used to manage authentication configurations.
*
* @author Musthaq Ahamad <[email protected]>
* @date 2025-05-05
* @module AuthConfigs
*/
import ComposioClient from '@composio/client';
import {
AuthConfigDeleteResponse,
AuthConfigUpdateResponse,
AuthConfigUpdateStatusResponse,
} from '@composio/client/resources/auth-configs';
import {
AuthConfigListParams,
AuthConfigListParamsSchema,
AuthConfigListResponse,
AuthConfigRetrieveResponse,
AuthConfigUpdateParams,
AuthConfigUpdateParamsSchema,
CreateAuthConfigParams,
CreateAuthConfigParamsSchema,
CreateAuthConfigResponse,
} from '../types/authConfigs.types';
import { ValidationError } from '../errors/ValidationErrors';
import { telemetry } from '../telemetry/Telemetry';
import {
transformAuthConfigListResponse,
transformAuthConfigRetrieveResponse,
transformCreateAuthConfigResponse,
} from '../utils/transformers/authConfigs';
import { ComposioRequestOptions } from '../types/requestOptions.types';
import { withCancellation } from '../utils/cancellation';
/**
* AuthConfigs class
*
* This class is used to manage authentication configurations in the Composio SDK.
* Auth configs are used to configure authentication providers and settings.
*/
export class AuthConfigs {
private client: ComposioClient;
constructor(client: ComposioClient) {
this.client = client;
telemetry.instrument(this, 'AuthConfigs');
}
/**
* Protected getter for the client instance.
* This is primarily used for testing purposes.
* @protected
*/
protected getClient(): ComposioClient {
return this.client;
}
/**
* Lists authentication configurations based on provided filter criteria.
*
* This method retrieves auth configs from the Composio API, transforms them to the SDK format,
* and supports filtering by various parameters.
*
* @param {AuthConfigListParams} [query] - Optional query parameters for filtering auth configs
* @returns {Promise<AuthConfigListResponse>} A paginated list of auth configurations
* @throws {ValidationError} If the query parameters or response fail validation
*
* @example
* ```typescript
* // List all auth configs
* const allConfigs = await composio.authConfigs.list();
*
* // List auth configs for a specific toolkit
* const githubConfigs = await composio.authConfigs.list({
* toolkit: 'github'
* });
*
* // Search auth configs by name or id
* const searchedConfigs = await composio.authConfigs.list({
* search: 'github',
* showDisabled: true
* });
*
* // List Composio-managed auth configs
* const managedConfigs = await composio.authConfigs.list({
* isComposioManaged: true
* });
* ```
*/
async list(
query?: AuthConfigListParams,
requestOptions?: ComposioRequestOptions
): Promise<AuthConfigListResponse> {
const parsedQuery = query ? AuthConfigListParamsSchema.parse(query) : undefined;
const listParams = {
cursor: parsedQuery?.cursor,
is_composio_managed: parsedQuery?.isComposioManaged,
limit: parsedQuery?.limit,
search: parsedQuery?.search,
show_disabled: parsedQuery?.showDisabled,
toolkit_slug: parsedQuery?.toolkit,
};
const result = await withCancellation(
() => this.client.authConfigs.list(listParams, requestOptions),
requestOptions?.signal
);
return transformAuthConfigListResponse(result);
}
/**
* Create a new auth config
* @param {string} toolkit - Unique identifier of the toolkit
* @param {CreateAuthConfigParams} options - Options for creating a new auth config
* @returns {Promise<CreateAuthConfigResponse>} Created auth config
*
* @example
* const authConfig = await authConfigs.create('my-toolkit', {
* type: AuthConfigTypes.CUSTOM,
* name: 'My Custom Auth Config',
* authScheme: AuthSchemeTypes.API_KEY,
* credentials: {
* apiKey: '1234567890',
* },
* });
*
* @link https://docs.composio.dev/reference/auth-configs/create-auth-config
*/
async create(
toolkit: string,
options: CreateAuthConfigParams = { type: 'use_composio_managed_auth' },
requestOptions?: ComposioRequestOptions
): Promise<CreateAuthConfigResponse> {
const parsedOptions = CreateAuthConfigParamsSchema.safeParse(options);
if (parsedOptions.error) {
throw new ValidationError('Failed to parse auth config create options', {
cause: parsedOptions.error,
});
}
const createBody = {
toolkit: {
slug: toolkit,
},
auth_config:
parsedOptions.data.type === 'use_custom_auth'
? {
type: parsedOptions.data.type,
name: parsedOptions.data.name,
authScheme: parsedOptions.data.authScheme,
credentials: parsedOptions.data.credentials,
is_enabled_for_tool_router: parsedOptions.data.isEnabledForToolRouter,
proxy_config: parsedOptions.data.proxyConfig
? {
proxy_url: parsedOptions.data.proxyConfig.proxyUrl,
proxy_auth_key: parsedOptions.data.proxyConfig.proxyAuthKey,
}
: undefined,
tool_access_config: parsedOptions.data.toolAccessConfig
? {
tools_for_connected_account_creation:
parsedOptions.data.toolAccessConfig.toolsForConnectedAccountCreation,
}
: undefined,
}
: {
type: parsedOptions.data.type,
credentials: parsedOptions.data.credentials,
name: parsedOptions.data.name,
is_enabled_for_tool_router: parsedOptions.data.isEnabledForToolRouter,
tool_access_config: parsedOptions.data.toolAccessConfig
? {
tools_for_connected_account_creation:
parsedOptions.data.toolAccessConfig.toolsForConnectedAccountCreation,
}
: undefined,
},
};
const result = await withCancellation(
() => this.client.authConfigs.create(createBody, requestOptions),
requestOptions?.signal
);
return transformCreateAuthConfigResponse(result);
}
/**
* Retrieves a specific authentication configuration by its ID.
*
* This method fetches detailed information about a single auth config
* and transforms the response to the SDK's standardized format.
*
* @param {string} nanoid - The unique identifier of the auth config to retrieve
* @returns {Promise<AuthConfigRetrieveResponse>} The auth config details
* @throws {Error} If the auth config cannot be found or an API error occurs
* @throws {ValidationError} If the response fails validation
*
* @example
* ```typescript
* // Get an auth config by ID
* const authConfig = await composio.authConfigs.get('auth_abc123');
* console.log(authConfig.name); // e.g., 'GitHub Auth'
* console.log(authConfig.toolkit.slug); // e.g., 'github'
* ```
*/
async get(
nanoid: string,
requestOptions?: ComposioRequestOptions
): Promise<AuthConfigRetrieveResponse> {
const result = await withCancellation(
() => this.client.authConfigs.retrieve(nanoid, requestOptions),
requestOptions?.signal
);
return transformAuthConfigRetrieveResponse(result);
}
/**
* Updates an existing authentication configuration.
*
* This method allows you to modify properties of an auth config such as credentials,
* scopes, or tool restrictions. The update type (custom or default) determines which
* fields can be updated.
*
* @param {string} nanoid - The unique identifier of the auth config to update
* @param {AuthConfigUpdateParams} data - The data to update, which can be either custom or default type
* @returns {Promise<AuthConfigUpdateResponse>} The updated auth config
* @throws {ValidationError} If the update parameters are invalid
* @throws {Error} If the auth config cannot be found or updated
*
* @example
* ```typescript
* // Update a custom auth config with new credentials
* const updatedConfig = await composio.authConfigs.update('auth_abc123', {
* type: 'custom',
* credentials: {
* apiKey: 'new-api-key-value'
* }
* });
*
* // Update a default auth config with new scopes
* const updatedConfig = await composio.authConfigs.update('auth_abc123', {
* type: 'default',
* scopes: ['read:user', 'repo']
* });
* ```
*/
async update(
nanoid: string,
data: AuthConfigUpdateParams,
requestOptions?: ComposioRequestOptions
): Promise<AuthConfigUpdateResponse> {
const parsedData = AuthConfigUpdateParamsSchema.safeParse(data);
if (parsedData.error) {
throw new ValidationError('Failed to parse auth config update data', {
cause: parsedData.error,
});
}
const updateBody =
parsedData.data.type === 'custom'
? {
type: 'custom' as const,
credentials: parsedData.data.credentials,
is_enabled_for_tool_router: parsedData.data.isEnabledForToolRouter,
tool_access_config: {
tools_for_connected_account_creation:
parsedData.data.toolAccessConfig?.toolsForConnectedAccountCreation,
tools_available_for_execution:
parsedData.data.toolAccessConfig?.toolsAvailableForExecution ??
parsedData.data.restrictToFollowingTools,
},
}
: {
type: 'default' as const,
scopes: parsedData.data.scopes,
is_enabled_for_tool_router: parsedData.data.isEnabledForToolRouter,
tool_access_config: {
tools_for_connected_account_creation:
parsedData.data.toolAccessConfig?.toolsForConnectedAccountCreation,
tools_available_for_execution:
parsedData.data.toolAccessConfig?.toolsAvailableForExecution ??
parsedData.data.restrictToFollowingTools,
},
};
return withCancellation(
() => this.client.authConfigs.update(nanoid, updateBody, requestOptions),
requestOptions?.signal
);
}
/**
* Deletes an authentication configuration.
*
* This method permanently removes an auth config from the Composio platform.
* This action cannot be undone and will prevent any connected accounts that use
* this auth config from functioning.
*
* @param {string} nanoid - The unique identifier of the auth config to delete
* @returns {Promise<AuthConfigDeleteResponse>} The deletion response
* @throws {Error} If the auth config doesn't exist or cannot be deleted
*
* @example
* ```typescript
* // Delete an auth config
* await composio.authConfigs.delete('auth_abc123');
* ```
*/
async delete(
nanoid: string,
requestOptions?: ComposioRequestOptions
): Promise<AuthConfigDeleteResponse> {
return withCancellation(
() => this.client.authConfigs.delete(nanoid, undefined, requestOptions),
requestOptions?.signal
);
}
/**
* Updates the status of an authentication configuration.
*
* This method allows you to enable or disable an auth config. When disabled,
* the auth config cannot be used to create new connected accounts or authenticate
* with third-party services.
*
* @param {string} status - The status to set ('ENABLED' or 'DISABLED')
* @param {string} nanoid - The unique identifier of the auth config
* @returns {Promise<AuthConfigUpdateStatusResponse>} The updated auth config details
* @throws {Error} If the auth config cannot be found or the status cannot be updated
*
* @example
* ```typescript
* // Disable an auth config
* await composio.authConfigs.updateStatus('DISABLED', 'auth_abc123');
*
* // Enable an auth config
* await composio.authConfigs.updateStatus('ENABLED', 'auth_abc123');
* ```
*/
async updateStatus(
status: 'ENABLED' | 'DISABLED',
nanoid: string,
requestOptions?: ComposioRequestOptions
): Promise<AuthConfigUpdateStatusResponse> {
return withCancellation(
() => this.client.authConfigs.updateStatus(status, { nanoid }, requestOptions),
requestOptions?.signal
);
}
/**
* Enables an authentication configuration.
*
* This is a convenience method that calls updateStatus with 'ENABLED'.
* When enabled, the auth config can be used to create new connected accounts
* and authenticate with third-party services.
*
* @param {string} nanoid - The unique identifier of the auth config to enable
* @returns {Promise<AuthConfigUpdateStatusResponse>} The updated auth config details
* @throws {Error} If the auth config cannot be found or enabled
*
* @example
* ```typescript
* // Enable an auth config
* await composio.authConfigs.enable('auth_abc123');
* ```
*/
async enable(
nanoid: string,
requestOptions?: ComposioRequestOptions
): Promise<AuthConfigUpdateStatusResponse> {
return withCancellation(
() => this.client.authConfigs.updateStatus('ENABLED', { nanoid }, requestOptions),
requestOptions?.signal
);
}
/**
* Disables an authentication configuration.
*
* This is a convenience method that calls updateStatus with 'DISABLED'.
* When disabled, the auth config cannot be used to create new connected accounts
* or authenticate with third-party services, but existing connections may continue to work.
*
* @param {string} nanoid - The unique identifier of the auth config to disable
* @returns {Promise<AuthConfigUpdateStatusResponse>} The updated auth config details
* @throws {Error} If the auth config cannot be found or disabled
*
* @example
* ```typescript
* // Disable an auth config
* await composio.authConfigs.disable('auth_abc123');
* ```
*/
async disable(
nanoid: string,
requestOptions?: ComposioRequestOptions
): Promise<AuthConfigUpdateStatusResponse> {
return withCancellation(
() => this.client.authConfigs.updateStatus('DISABLED', { nanoid }, requestOptions),
requestOptions?.signal
);
}
}