Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Auth Configs API
The AuthConfigs class provides methods to manage authentication configurations for toolkits. Auth configs define how authentication works for a particular toolkit, specifying the auth scheme (OAuth2, API Key, etc.) and other authentication-related details.
Methods
list(query?)
Lists all auth configs based on provided filter criteria.
// List all auth configs
const allAuthConfigs = await composio.authConfigs.list();
// List auth configs for a specific toolkit
const githubAuthConfigs = await composio.authConfigs.list({
toolkit: 'github',
});
// Search auth configs by name or id and include disabled configs
const searchedAuthConfigs = await composio.authConfigs.list({
search: 'github',
showDisabled: true,
});
Parameters:
query(AuthConfigListParams): Optional query parameters for filtering auth configs
Returns: Promise - A paginated list of auth configs
Throws: ValidationError if the query fails validation against the expected schema
get(id)
Retrieves a specific auth config by its ID.
// Get an auth config by ID
const authConfig = await composio.authConfigs.get('auth_config_123');
console.log(authConfig.name); // Name of the auth config
Parameters:
id(string): The unique identifier of the auth config
Returns: Promise - The auth config details
Throws: ComposioAuthConfigNotFoundError if the auth config cannot be found
create(toolkit, data)
Creates a new auth config for a toolkit.
// Create an auth config for GitHub
const authConfig = await composio.authConfigs.create('github', {
type: 'use_composio_managed_auth',
name: 'GitHub Auth Config',
});
Parameters:
toolkit(string): The slug of the toolkit to create an auth config fordata(AuthConfigCreateParams): The parameters for creating the auth config
Returns: Promise - The created auth config
Throws:
- ValidationError if the parameters fail validation
- ComposioToolNotFoundError if the toolkit cannot be found
update(id, data)
Updates an existing auth config.
// Update a custom auth config with new credentials
const updatedAuthConfig = await composio.authConfigs.update('auth_config_123', {
type: 'custom',
credentials: {
client_id: 'new_client_id',
client_secret: 'new_client_secret',
},
toolAccessConfig: {
toolsAvailableForExecution: ['GITHUB_STAR_A_REPOSITORY_FOR_THE_AUTHENTICATED_USER'],
},
});
// Update a default auth config with new scopes
const updatedDefaultAuth = await composio.authConfigs.update('auth_config_456', {
type: 'default',
scopes: 'read:user,repo',
toolAccessConfig: {
toolsAvailableForExecution: ['GITHUB_GET_A_REPOSITORY', 'GITHUB_LIST_REPOSITORIES_FOR_A_USER'],
},
});
Parameters:
id(string): The unique identifier of the auth config to updatedata(AuthConfigUpdateParams): The parameters for updating the auth config. Must be a discriminated union with either:{ type: 'custom', credentials: Record<string, unknown>, toolAccessConfig?: {...} }{ type: 'default', scopes: string, toolAccessConfig?: {...} }
Returns: Promise - The updated auth config
Throws:
- ValidationError if the update parameters are invalid
- ComposioAuthConfigNotFoundError if the auth config cannot be found
delete(id)
Deletes an auth config.
// Delete an auth config
await composio.authConfigs.delete('auth_config_123');
Parameters:
id(string): The unique identifier of the auth config to delete
Returns: Promise - The deletion response
Throws: Error if the auth config doesn't exist or cannot be deleted
Types
AuthConfigListParams
interface AuthConfigListParams {
cursor?: string; // Pagination cursor
limit?: number; // Limit the number of results
search?: string; // Search auth configs by name or id
showDisabled?: boolean; // Include disabled auth configs
toolkit?: string; // Filter by toolkit slug
isComposioManaged?: boolean; // Filter by Composio-managed auth configs
}
AuthConfigListResponse
interface AuthConfigListResponse {
items: AuthConfigRetrieveResponse[]; // List of auth configs
nextCursor: string | null; // Pagination cursor
totalPages: number; // Total number of pages
}
AuthConfigRetrieveResponse
interface AuthConfigRetrieveResponse {
id: string; // Auth config ID
name: string; // Name of the auth config
type: AuthConfigType; // Type of auth config
toolkit: {
// Associated toolkit
id: string; // Toolkit ID
slug: string; // Toolkit slug
name: string; // Toolkit name
};
authScheme: AuthSchemeType; // Auth scheme (e.g., 'oauth2', 'api_key')
isDisabled: boolean; // Whether the auth config is disabled
fields: Record<string, unknown>; // Configuration fields
meta: Record<string, unknown>; // Additional metadata
createdAt: string; // Creation timestamp
updatedAt: string; // Last update timestamp
}
AuthConfigCreateParams
interface AuthConfigCreateParams {
type: AuthConfigType; // Type of auth config
name: string; // Name of the auth config
fields?: Record<string, unknown>; // Configuration fields
}
AuthConfigUpdateParams
// Discriminated union type for updating auth configs
type AuthConfigUpdateParams =
| {
type: 'custom';
credentials: Record<string, string | number | boolean | unknown>;
toolAccessConfig?: {
toolsAvailableForExecution?: string[];
toolsForConnectedAccountCreation?: string[];
};
/** @deprecated Use toolAccessConfig instead */
restrictToFollowingTools?: string[];
}
| {
type: 'default';
scopes: string;
toolAccessConfig?: {
toolsAvailableForExecution?: string[];
toolsForConnectedAccountCreation?: string[];
};
/** @deprecated Use toolAccessConfig instead */
restrictToFollowingTools?: string[];
};
AuthConfigType
Auth config types are defined as an enum:
enum AuthConfigTypes {
USE_COMPOSIO_MANAGED_AUTH = 'use_composio_managed_auth',
SERVICE_CONNECTION = 'service_connection',
USER_CREDENTIALS = 'user_credentials',
CUSTOM_AUTH = 'custom_auth',
NO_AUTH = 'no_auth',
}
AuthSchemeType
Auth scheme types are defined as an enum:
enum AuthSchemeTypes {
OAUTH2 = 'oauth2',
API_KEY = 'api_key',
BASIC_AUTH = 'basic_auth',
CUSTOM = 'custom',
NO_AUTH = 'no_auth',
}