Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

6.6 KB
Raw Blame

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 for
  • data (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 update
  • data (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',
}