Authentication

Learn how to configure and manage authentication in the Composio SDK

Authentication

Authentication configurations (Auth Configs) define how users authenticate with third-party services in the Composio SDK. They specify the authentication method, required credentials, and permissions needed to connect to external platforms.

Overview

The AuthConfigs class manages authentication configurations that control how connected accounts authenticate with toolkits. Auth configs support various authentication schemes including OAuth2, API keys, and basic authentication.

Source: ts/packages/core/src/models/AuthConfigs.ts

Authentication Schemes

Composio supports multiple authentication schemes:

• OAUTH2 - OAuth 2.0 authentication
• OAUTH1 - OAuth 1.0 authentication
• API_KEY - API key-based authentication
• BASIC - Basic username/password authentication
• BEARER_TOKEN - Bearer token authentication
• NO_AUTH - No authentication required

Listing Auth Configs

List All Auth Configs

// List all auth configs
const allConfigs = await composio.authConfigs.list();

Filter by Toolkit

// List auth configs for a specific toolkit
const githubConfigs = await composio.authConfigs.list({
  toolkit: 'github'
});

Filter by Management Type

// List Composio-managed auth configs
const managedConfigs = await composio.authConfigs.list({
  isComposioManaged: true
});

// List custom auth configs
const customConfigs = await composio.authConfigs.list({
  isComposioManaged: false
});

Pagination

// List with pagination
const configs = await composio.authConfigs.list({
  limit: 20,
  cursor: 'next_page_cursor'
});

Creating Auth Configs

Composio-Managed Authentication

Use Composio’s built-in OAuth apps (recommended for quick setup):

import { AuthConfigTypes } from '@composio/core';

const authConfig = await composio.authConfigs.create('github', {
  type: 'use_composio_managed_auth',
  name: 'GitHub Auth Config'
});

console.log('Auth Config ID:', authConfig.id);

Composio-managed authentication uses Composio’s pre-configured OAuth applications, making it easy to get started without registering your own OAuth apps.

Custom Authentication

Use your own credentials and OAuth apps:

import { AuthSchemeTypes } from '@composio/core';

// OAuth2 with custom credentials
const authConfig = await composio.authConfigs.create('github', {
  type: 'use_custom_auth',
  name: 'My GitHub OAuth App',
  authScheme: AuthSchemeTypes.OAUTH2,
  credentials: {
    client_id: 'your_client_id',
    client_secret: 'your_client_secret',
    scopes: ['repo', 'user']
  }
});

// API Key authentication
const authConfig = await composio.authConfigs.create('custom-api', {
  type: 'use_custom_auth',
  name: 'Custom API Key Auth',
  authScheme: AuthSchemeTypes.API_KEY,
  credentials: {
    api_key: 'your_api_key'
  }
});

// Basic authentication
const authConfig = await composio.authConfigs.create('custom-service', {
  type: 'use_custom_auth',
  name: 'Basic Auth Config',
  authScheme: AuthSchemeTypes.BASIC,
  credentials: {
    username: 'your_username',
    password: 'your_password'
  }
});

Advanced Configuration Options

// With tool access restrictions
const authConfig = await composio.authConfigs.create('github', {
  type: 'use_custom_auth',
  name: 'Limited GitHub Access',
  authScheme: AuthSchemeTypes.OAUTH2,
  credentials: {
    client_id: 'your_client_id',
    client_secret: 'your_client_secret'
  },
  toolAccessConfig: {
    toolsForConnectedAccountCreation: ['GITHUB_GET_USER'],
    toolsAvailableForExecution: ['GITHUB_GET_REPOS', 'GITHUB_CREATE_ISSUE']
  },
  isEnabledForToolRouter: true
});

// With proxy configuration
const authConfig = await composio.authConfigs.create('custom-api', {
  type: 'use_custom_auth',
  name: 'Proxied API Access',
  authScheme: AuthSchemeTypes.API_KEY,
  credentials: {
    api_key: 'your_api_key'
  },
  proxyConfig: {
    proxyUrl: 'https://proxy.example.com',
    proxyAuthKey: 'proxy_auth_key'
  }
});

toolAccessConfig.toolsForConnectedAccountCreation specifies which tools can be used during the connection creation process, while toolsAvailableForExecution restricts which tools can be executed using this auth config.

Retrieving Auth Configs

Get detailed information about a specific auth config:

// 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'
console.log(authConfig.authScheme); // e.g., 'OAUTH2'

Updating Auth Configs

Update Custom Auth Config

// Update credentials for a custom auth config
const updatedConfig = await composio.authConfigs.update('auth_abc123', {
  type: 'custom',
  credentials: {
    api_key: 'new-api-key-value'
  }
});

// Update tool access restrictions
const updatedConfig = await composio.authConfigs.update('auth_abc123', {
  type: 'custom',
  credentials: {
    client_id: 'existing_client_id',
    client_secret: 'existing_client_secret'
  },
  toolAccessConfig: {
    toolsAvailableForExecution: ['GITHUB_GET_REPOS', 'GITHUB_GET_USER']
  }
});

Update Default Auth Config

// Update scopes for a default auth config
const updatedConfig = await composio.authConfigs.update('auth_abc123', {
  type: 'default',
  scopes: ['read:user', 'repo', 'write:org']
});

// Enable for tool router
const updatedConfig = await composio.authConfigs.update('auth_abc123', {
  type: 'default',
  scopes: ['read:user'],
  isEnabledForToolRouter: true
});

The update type (‘custom’ or ‘default’) determines which fields can be modified. Custom auth configs allow credential updates, while default configs allow scope modifications.

Managing Auth Config Status

Enable/Disable Auth Configs

// Enable an auth config
await composio.authConfigs.enable('auth_abc123');

// Disable an auth config
await composio.authConfigs.disable('auth_abc123');

Update Status Explicitly

// Disable an auth config
await composio.authConfigs.updateStatus('DISABLED', 'auth_abc123');

// Enable an auth config
await composio.authConfigs.updateStatus('ENABLED', 'auth_abc123');

When an auth config is disabled, it cannot be used to create new connected accounts or authenticate with third-party services. Existing connections may continue to work.

Deleting Auth Configs

Deleting an auth config is permanent and cannot be undone. It will prevent any connected accounts using this auth config from functioning.

// Delete an auth config
await composio.authConfigs.delete('auth_abc123');

Auth Config Properties

Every auth config object contains:

• id - Unique identifier for the auth config
• name - Human-readable name
• toolkit - Associated toolkit information
• authScheme - Authentication scheme type (OAUTH2, API_KEY, etc.)
• isComposioManaged - Whether it uses Composio’s managed authentication
• isEnabled - Current status (enabled/disabled)
• isEnabledForToolRouter - Whether it can be used with tool router
• scopes - OAuth scopes (for OAuth-based configs)
• createdAt - Creation timestamp
• updatedAt - Last update timestamp

Complete Authentication Flow

import { Composio, AuthSchemeTypes } from '@composio/core';

const composio = new Composio({ apiKey: 'your-api-key' });

// Step 1: Create an auth config
const authConfig = await composio.authConfigs.create('github', {
  type: 'use_custom_auth',
  name: 'My GitHub App',
  authScheme: AuthSchemeTypes.OAUTH2,
  credentials: {
    client_id: process.env.GITHUB_CLIENT_ID,
    client_secret: process.env.GITHUB_CLIENT_SECRET,
    scopes: ['repo', 'user']
  }
});

console.log('Created auth config:', authConfig.id);

// Step 2: Create a connected account using the auth config
const connectionRequest = await composio.connectedAccounts.link(
  'user_123',
  authConfig.id
);

console.log('Redirect user to:', connectionRequest.redirectUrl);

// Step 3: Wait for user to complete authentication
const connectedAccount = await connectionRequest.waitForConnection();

console.log('Successfully connected:', connectedAccount.id);

// Step 4: Execute tools using the connected account
const result = await composio.tools.execute('GITHUB_GET_REPOS', {
  userId: 'user_123',
  connectedAccountId: connectedAccount.id,
  arguments: { owner: 'composio' }
});

Tool Access Control

Restrict which tools can be used with an auth config:

// Create auth config with tool restrictions
const authConfig = await composio.authConfigs.create('github', {
  type: 'use_custom_auth',
  name: 'Read-only GitHub Access',
  authScheme: AuthSchemeTypes.OAUTH2,
  credentials: {
    client_id: 'your_client_id',
    client_secret: 'your_client_secret',
    scopes: ['repo:read']
  },
  toolAccessConfig: {
    // Only these tools can be used during connection creation
    toolsForConnectedAccountCreation: ['GITHUB_GET_USER'],
    // Only these tools can be executed
    toolsAvailableForExecution: [
      'GITHUB_GET_REPOS',
      'GITHUB_GET_ISSUES',
      'GITHUB_GET_USER'
    ]
  }
});

Best Practices

Security

• Never hardcode credentials - use environment variables
• Rotate credentials regularly
• Use the minimum required OAuth scopes
• Enable auth configs only when needed
• Delete unused auth configs

Organization

• Use descriptive names for auth configs
• Create separate auth configs for different environments (dev, staging, prod)
• Document the purpose and scope of each auth config

Example: Environment-Based Auth Configs

const environment = process.env.NODE_ENV || 'development';

const authConfig = await composio.authConfigs.create('github', {
  type: 'use_custom_auth',
  name: `GitHub Auth - ${environment.toUpperCase()}`,
  authScheme: AuthSchemeTypes.OAUTH2,
  credentials: {
    client_id: process.env[`GITHUB_CLIENT_ID_${environment.toUpperCase()}`],
    client_secret: process.env[`GITHUB_CLIENT_SECRET_${environment.toUpperCase()}`],
    scopes: environment === 'production' ? ['repo'] : ['repo', 'delete_repo']
  }
});

Error Handling

Common errors when working with auth configs:

• ComposioAuthConfigNotFoundError - Auth config doesn’t exist
• ValidationError - Invalid parameters or credentials format
• API errors (400) - Invalid configuration or missing required fields
• API errors (404) - Toolkit or auth config not found

Example Error Handling

import { ComposioAuthConfigNotFoundError, ValidationError } from '@composio/core';

try {
  const authConfig = await composio.authConfigs.create('github', {
    type: 'use_custom_auth',
    name: 'GitHub Auth',
    authScheme: AuthSchemeTypes.OAUTH2,
    credentials: {
      client_id: 'invalid',
      client_secret: 'invalid'
    }
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.error('Invalid auth config parameters:', error.message);
  } else if (error.status === 400) {
    console.error('API rejected the auth config:', error.message);
  } else {
    throw error;
  }
}

Related Resources

• Connected Accounts - Use auth configs to create connections
• Toolkits - Services that require authentication
• Tools - Execute authenticated operations
• Providers - Integrate with AI frameworks