AuthConfigs API — Composio TypeScript SDK Reference

The AuthConfigs class manages authentication configurations — the bridge between your app’s OAuth credentials and Composio’s connected account system. An auth config specifies how users authenticate with a toolkit (OAuth2, API key, basic auth, etc.) and holds the application-level credentials (client ID, client secret, API keys) used to initiate connections.

When to use custom auth configs vs. Composio-managed

By default, Composio provides managed OAuth apps for all supported toolkits. You do not need to create an auth config to get started. Use custom auth configs when you need to:

Use your own OAuth application (custom client ID / client secret)
Configure specific OAuth scopes for your use case
Use API key, bearer token, or basic auth schemes
Restrict which tools are available for a given auth config

For development and evaluation, skip auth config creation and use Composio-managed OAuth by calling composio.toolkits.authorize(userId, toolkitSlug) directly — it creates a managed auth config automatically.

authConfigs.create()

Create a new authentication configuration for a toolkit.

composio.authConfigs.create(
  toolkit: string,
  options?: CreateAuthConfigParams
): Promise<CreateAuthConfigResponse>

toolkit

string

required

Toolkit slug to create the auth config for (e.g. 'github', 'gmail').

options

CreateAuthConfigParams

Auth config type and settings. Defaults to { type: 'use_composio_managed_auth' }.

Show Custom auth config (use_custom_auth)

type

"use_custom_auth"

required

Create a custom auth config with your own credentials.

authScheme

string

required

Authentication scheme. One of OAUTH2, OAUTH1, API_KEY, BEARER_TOKEN, BASIC, GOOGLE_SERVICE_ACCOUNT, NO_AUTH, BASIC_WITH_JWT, CALCOM_AUTH, SERVICE_ACCOUNT, SAML, DCR_OAUTH, S2S_OAUTH2.

credentials

Record<string, string | number | boolean>

required

Auth credentials — for OAuth2 this is { client_id, client_secret }, for API key this is { api_key }, etc.

name

string

Human-readable name for this auth config.

isEnabledForToolRouter

boolean

Whether this auth config can be used in tool router sessions.

toolAccessConfig.toolsForConnectedAccountCreation

string[]

Restrict which tools are shown during account connection.

proxyConfig.proxyUrl

string

Proxy URL for routing API calls through your infrastructure.

Show Composio-managed auth config (use_composio_managed_auth)

type

"use_composio_managed_auth"

required

Use Composio’s OAuth app. Composio manages the client credentials.

credentials.scopes

string | string[]

OAuth scopes to request. Overrides Composio’s default scopes for this toolkit.

name

string

Human-readable name for this auth config.

CreateAuthConfigResponse

string

Unique identifier for the new auth config.

authScheme

string

Authentication scheme used by this config.

isComposioManaged

boolean

Whether this auth config uses Composio’s managed OAuth app.

toolkit

string

Toolkit slug this auth config belongs to.

authConfigs.get()

Retrieve an auth config by its ID.

composio.authConfigs.get(nanoid: string): Promise<AuthConfigRetrieveResponse>

AuthConfigRetrieveResponse

string

Auth config ID.

name

string

Auth config name.

toolkit

{ slug: string; logo: string }

The toolkit this auth config is for.

authScheme

string

Authentication scheme (OAUTH2, API_KEY, etc.).

status

"ENABLED" | "DISABLED"

Whether this auth config is currently active.

isComposioManaged

boolean

Whether Composio manages the OAuth app credentials.

noOfConnections

number

Number of connected accounts using this auth config.

isEnabledForToolRouter

boolean

Whether this auth config can be used in tool router sessions.

toolAccessConfig

object

Per-auth-config tool access restrictions — toolsAvailableForExecution and toolsForConnectedAccountCreation.

authConfigs.list()

List auth configs with optional filtering.

composio.authConfigs.list(query?: AuthConfigListParams): Promise<AuthConfigListResponse>

query.toolkit

string

Filter by toolkit slug.

query.isComposioManaged

boolean

Filter to only Composio-managed or only custom auth configs.

query.cursor

string

Pagination cursor.

query.limit

number

Maximum items per page.

AuthConfigListResponse

items

AuthConfigRetrieveResponse[]

Auth configs for the current page.

nextCursor

string | null

Cursor for the next page.

totalPages

number

Total number of pages.

authConfigs.update()

Update an existing auth config’s credentials, scopes, or tool access settings.

composio.authConfigs.update(
  nanoid: string,
  data: AuthConfigUpdateParams
): Promise<AuthConfigUpdateResponse>

data.type

"custom" | "default"

required

'custom' to update credentials on a custom auth config. 'default' to update scopes on a Composio-managed auth config.

data.credentials

object

New credentials. Only valid when type: 'custom'.

data.scopes

string

New OAuth scopes. Only valid when type: 'default'.

data.toolAccessConfig.toolsAvailableForExecution

string[]

Restrict which tools can be executed via connected accounts under this auth config.

authConfigs.delete()

Permanently delete an auth config. This will prevent connected accounts that use this config from functioning.

composio.authConfigs.delete(nanoid: string): Promise<AuthConfigDeleteResponse>

authConfigs.enable() / disable()

Enable or disable an auth config. Disabled auth configs cannot be used to create new connected accounts.

composio.authConfigs.enable(nanoid: string): Promise<AuthConfigUpdateStatusResponse>
composio.authConfigs.disable(nanoid: string): Promise<AuthConfigUpdateStatusResponse>

Examples

Custom GitHub OAuth app
API key auth config
List and inspect
Restrict tool access

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

const composio = new Composio();

// Create a custom OAuth2 auth config with your own GitHub app
const authConfig = await composio.authConfigs.create('github', {
  type: 'use_custom_auth',
  authScheme: 'OAUTH2',
  name: 'My GitHub OAuth App',
  credentials: {
    client_id: process.env.GITHUB_CLIENT_ID!,
    client_secret: process.env.GITHUB_CLIENT_SECRET!,
  },
});

console.log('Auth config created:', authConfig.id);

// Use it to initiate connections
const connectionRequest = await composio.connectedAccounts.link(
  'user_123',
  authConfig.id,
  { callbackUrl: 'https://your-app.com/callback' }
);

console.log('OAuth URL:', connectionRequest.redirectUrl);

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

const composio = new Composio();

// Create an API key auth config
const authConfig = await composio.authConfigs.create('openai', {
  type: 'use_custom_auth',
  authScheme: 'API_KEY',
  name: 'OpenAI API Key',
  credentials: {
    api_key: process.env.OPENAI_API_KEY!,
  },
});

// Connect a user with this API key (no redirect needed)
const connectionRequest = await composio.connectedAccounts.initiate(
  'user_123',
  authConfig.id
);

const account = await connectionRequest.waitForConnection();
console.log('Connected:', account.id);

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

const composio = new Composio();

// List all GitHub auth configs
const { items } = await composio.authConfigs.list({ toolkit: 'github' });

for (const config of items) {
  console.log(`${config.name} (${config.id}): ${config.status}`);
  console.log(`  Connections: ${config.noOfConnections}`);
  console.log(`  Composio-managed: ${config.isComposioManaged}`);
}

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

const composio = new Composio();

// Update an existing auth config to restrict tool access
await composio.authConfigs.update('auth_abc123', {
  type: 'custom',
  toolAccessConfig: {
    toolsAvailableForExecution: [
      'GITHUB_CREATE_ISSUE',
      'GITHUB_LIST_PULL_REQUESTS',
      'GITHUB_GET_REPOS',
    ],
  },
});

TypeScript SDK

Python SDK

REST API

AuthConfigs API — Composio TypeScript SDK Reference

When to use custom auth configs vs. Composio-managed

authConfigs.create()

CreateAuthConfigResponse

authConfigs.get()

AuthConfigRetrieveResponse

authConfigs.list()

AuthConfigListResponse

authConfigs.update()

authConfigs.delete()

authConfigs.enable() / disable()

Examples

Build docs developers (and LLMs) love

TypeScript SDK

Python SDK

REST API

Documentation Index

​When to use custom auth configs vs. Composio-managed

​authConfigs.create()

​CreateAuthConfigResponse

​authConfigs.get()

​AuthConfigRetrieveResponse

​authConfigs.list()

​AuthConfigListResponse

​authConfigs.update()

​authConfigs.delete()

​authConfigs.enable() / disable()

​Examples

Build docs developers (and LLMs) love

When to use custom auth configs vs. Composio-managed

authConfigs.create()

CreateAuthConfigResponse

authConfigs.get()

AuthConfigRetrieveResponse

authConfigs.list()

AuthConfigListResponse

authConfigs.update()

authConfigs.delete()

authConfigs.enable() / disable()

Examples