Auth Configs API

Manage authentication configurations for toolkits

The authConfigs API manages authentication configurations that define how users authenticate with toolkits. Each auth config specifies the authentication method (OAuth2, API Key, Basic, etc.) and credentials.

Methods

list()

List authentication configurations.

async list(query?: AuthConfigListParams): Promise<AuthConfigListResponse>

query · AuthConfigListParams

Show properties

toolkit · string

Filter by toolkit slug

isComposioManaged · boolean

Filter by management type

cursor · string

Pagination cursor

limit · number

Maximum results

List all configs

const configs = await composio.authConfigs.list();

configs.items.forEach(config => {
  console.log(config.id, config.name, config.toolkit.slug);
});

Filter by toolkit

const githubConfigs = await composio.authConfigs.list({
  toolkit: 'github'
});

Composio-managed only

const managedConfigs = await composio.authConfigs.list({
  isComposioManaged: true
});

get()

Retrieve a specific auth config by ID.

async get(nanoid: string): Promise<AuthConfigRetrieveResponse>

nanoid · string · required

Auth config ID

Example:

const config = await composio.authConfigs.get('auth_abc123');

console.log(config.name); // "GitHub OAuth"
console.log(config.toolkit.slug); // "github"
console.log(config.authScheme); // "OAUTH2"

create()

Create a new auth config.

async create(
  toolkit: string,
  options?: CreateAuthConfigParams
): Promise<CreateAuthConfigResponse>

toolkit · string · required

Toolkit slug to create config for

options · CreateAuthConfigParams

Show properties

type · string · required

use_composio_managed_auth or use_custom_auth

name · string

Human-readable name

authScheme · AuthSchemeType

Auth type (for custom auth): OAUTH2, API_KEY, BASIC, etc.

credentials · Record<string, unknown>

Auth credentials (for custom auth)

isEnabledForToolRouter · boolean

Enable for Tool Router

toolAccessConfig · object

Tool access restrictions

Composio-managed auth

const config = await composio.authConfigs.create('github', {
  type: 'use_composio_managed_auth',
  name: 'GitHub OAuth (Composio)'
});

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

Custom OAuth2

const config = await composio.authConfigs.create('github', {
  type: 'use_custom_auth',
  name: 'GitHub OAuth (Custom)',
  authScheme: 'OAUTH2',
  credentials: {
    client_id: 'your_client_id',
    client_secret: 'your_client_secret',
    scopes: ['repo', 'user']
  }
});

API Key auth

const config = await composio.authConfigs.create('openai', {
  type: 'use_custom_auth',
  name: 'OpenAI API Key',
  authScheme: 'API_KEY',
  credentials: {
    api_key: 'sk-...' // Your API key
  }
});

With tool restrictions

const config = await composio.authConfigs.create('github', {
  type: 'use_custom_auth',
  name: 'GitHub Limited',
  authScheme: 'OAUTH2',
  credentials: { /* ... */ },
  toolAccessConfig: {
    toolsForConnectedAccountCreation: [
      'GITHUB_GET_REPOS',
      'GITHUB_CREATE_ISSUE'
    ]
  }
});

update()

Update an existing auth config.

async update(
  nanoid: string,
  data: AuthConfigUpdateParams
): Promise<AuthConfigUpdateResponse>

nanoid · string · required

Auth config ID

data · AuthConfigUpdateParams · required

Show properties

type · string · required

custom or default

credentials · Record<string, unknown>

Updated credentials (for custom type)

scopes · string[]

Updated scopes (for default type)

isEnabledForToolRouter · boolean

Enable/disable for Tool Router

toolAccessConfig · object

Tool access restrictions

Update credentials

await composio.authConfigs.update('auth_abc123', {
  type: 'custom',
  credentials: {
    client_id: 'new_client_id',
    client_secret: 'new_client_secret'
  }
});

Update scopes

await composio.authConfigs.update('auth_abc123', {
  type: 'default',
  scopes: ['repo', 'user', 'admin:org']
});

delete()

Delete an auth config.

async delete(nanoid: string): Promise<AuthConfigDeleteResponse>

Deleting an auth config will prevent connected accounts using it from functioning.

Example:

await composio.authConfigs.delete('auth_abc123');
console.log('Auth config deleted');

enable() / disable()

Enable or disable an auth config.

async enable(nanoid: string): Promise<AuthConfigUpdateStatusResponse>
async disable(nanoid: string): Promise<AuthConfigUpdateStatusResponse>

Example:

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

// Re-enable it
await composio.authConfigs.enable('auth_abc123');

updateStatus()

Update auth config status.

async updateStatus(
  status: 'ENABLED' | 'DISABLED',
  nanoid: string
): Promise<AuthConfigUpdateStatusResponse>

Example:

await composio.authConfigs.updateStatus('DISABLED', 'auth_abc123');

Types

AuthConfigRetrieveResponse

interface AuthConfigRetrieveResponse {
  id: string; // Config ID
  name: string; // Config name
  toolkit: { // Associated toolkit
    slug: string;
    name: string;
  };
  authScheme: AuthSchemeType; // Auth type
  isComposioManaged: boolean; // Managed by Composio
  isEnabledForToolRouter: boolean; // Available in Tool Router
  status: 'ENABLED' | 'DISABLED';
  createdAt: string; // ISO timestamp
  updatedAt: string; // ISO timestamp
}

AuthSchemeType

type AuthSchemeType =
  | 'OAUTH2' // OAuth 2.0
  | 'OAUTH1' // OAuth 1.0a
  | 'API_KEY' // API key
  | 'BASIC' // Basic auth (username/password)
  | 'BEARER_TOKEN' // Bearer token
  | 'NO_AUTH'; // No authentication required

CreateAuthConfigParams

type CreateAuthConfigParams =
  | {
      type: 'use_composio_managed_auth';
      name?: string;
      isEnabledForToolRouter?: boolean;
      toolAccessConfig?: ToolAccessConfig;
    }
  | {
      type: 'use_custom_auth';
      name: string;
      authScheme: AuthSchemeType;
      credentials: Record<string, unknown>;
      isEnabledForToolRouter?: boolean;
      proxyConfig?: ProxyConfig;
      toolAccessConfig?: ToolAccessConfig;
    };

Common Auth Schemes

OAuth2

Required credentials:

{
  client_id: string;
  client_secret: string;
  scopes?: string[]; // Optional scopes
}

API Key

Required credentials:

{
  api_key: string;
}

Basic Auth

Required credentials:

{
  username: string;
  password: string;
}

Bearer Token

Required credentials:

{
  token: string;
}

Next Steps

Connected Accounts

Create user connections

Toolkits

Browse available toolkits

Tools API

Execute tools

Tool Router

Intelligent connection management