auth-config: typed authentication configurations

typed authentication configurations for integrations with full TypeScript support, validation, and automatic processing.

overview

the auth-config system provides a type-safe way to configure authentication for API integrations. it supports multiple authentication methods, dynamic URL generation, and ensures configuration correctness at compile time.

key benefits

• type safety: full TypeScript support with compile-time validation
• multiple auth methods: api keys, oauth2, basic auth, bearer tokens
• dynamic configuration: urls and headers that adapt to user input
• validation: automatic schema validation and error reporting
• backwards compatibility: seamless migration from legacy configurations

quick start

create a config.ts file in your app directory:

import {
  createAuthSchemeConfig,
  createToolkitConfig,
} from '@composio/auth-config'

const API_KEY_AUTH = createAuthSchemeConfig({
  mode: 'API_KEY',
  strictFields: {
    headers: {
      generic_api_key: {
        display_name: 'API Key',
        description: 'Your API key from account settings',
        required: true,
        field_type: 'connection_field',
        is_secret: true,
        legacy_template_name: 'api_key',
      },
    },
  },
  headers: (fields) => ({
    Authorization: `Bearer ${fields.generic_api_key}`,
  }),
  name: 'api_key_auth',
})

const config = createToolkitConfig({
  authSchemes: [API_KEY_AUTH],
  baseUrl: () => 'https://api.example.com/v1',
  name: 'Example Service',
  logo: 'https://example.com/logo.svg',
  unique_key: 'example',
  categories: ['productivity'],
  description: 'Example service integration',
})

export default config

authentication schemes

api key authentication

most common pattern for services using api keys:

const API_KEY_AUTH = createAuthSchemeConfig({
  mode: 'API_KEY',
  strictFields: {
    headers: {
      generic_api_key: {
        display_name: 'API Key',
        description: 'Get this from your account settings',
        required: true,
        field_type: 'connection_field',
        is_secret: true,
        legacy_template_name: 'api_key',
      },
    },
  },
  headers: (fields) => ({
    Authorization: `Bearer ${fields.generic_api_key}`,
  }),
  name: 'api_key_auth',
})

header variations

common authorization header patterns:

// bearer token (most common)
headers: (fields) => ({
  Authorization: `Bearer ${fields.generic_api_key}`,
})

// basic auth with api key
headers: (fields) => ({
  Authorization: `Basic ${fields.generic_api_key}`,
})

// custom header
headers: (fields) => ({
  'X-API-Key': fields.generic_api_key,
})

// multiple headers
headers: (fields) => ({
  Authorization: `Bearer ${fields.generic_api_key}`,
  'User-Agent': 'MyApp/1.0',
  Accept: 'application/json',
})

oauth2 authentication

for services supporting oauth2 flows:

const OAUTH_AUTH = createAuthSchemeConfig({
  mode: 'OAUTH2',
  strictFields: {
    headers: {
      bearer_token: {
        display_name: 'Access Token',
        description: 'Automatically managed OAuth2 access token',
        required: false,
        field_type: 'auth_config_field',
        is_secret: false,
        legacy_template_name: 'access_token',
      },
    },
  },
  token_url: () => 'https://api.example.com/oauth/token',
  authorization_url: () => 'https://api.example.com/oauth/authorize',
  default_scopes: () => ['read', 'write'],
  scope_separator: ' ',
  authorization_params: {
    response_type: 'code',
    access_type: 'offline',
    prompt: 'consent',
  },
  token_params: {
    grant_type: 'authorization_code',
  },
  disable_pkce: false,
  name: 'oauth_scheme',
})

oauth2 configuration options

• token_url: endpoint for exchanging codes for tokens
• refresh_url: endpoint for refreshing tokens (optional, defaults to token_url)
• exchange_url: endpoint for token exchange flows (optional, for providers like Meta)
• authorization_url: endpoint for user authorization
• default_scopes: default permissions requested
• scope_separator: separator for multiple scopes (usually space or comma)
• authorization_params: additional parameters for auth requests
• token_params: additional parameters for token requests
• token_access_request_method: HTTP method for token requests (e.g., 'POST')
• token_request_auth_method: authentication method for token requests ('basic' or 'request_body')
• refresh_access_request_method: HTTP method for refresh token requests (e.g., 'POST')
• refresh_request_auth_method: authentication method for refresh token requests ('basic' or 'request_body')
• refresh_params: additional parameters for refresh token requests
• disable_pkce: disable PKCE for older oauth2 implementations

basic authentication

for username/password authentication:

const BASIC_AUTH = createAuthSchemeConfig({
  mode: 'BASIC',
  strictFields: {
    headers: {},
    db: {
      username: {
        display_name: 'Username',
        description: 'Your account username',
        required: true,
        field_type: 'connection_field',
        is_secret: false,
        legacy_template_name: 'username',
      },
      password: {
        display_name: 'Password',
        description: 'Your account password',
        required: true,
        field_type: 'connection_field',
        is_secret: true,
        legacy_template_name: 'password',
      },
    },
  },
  name: 'basic_auth',
})

bearer token authentication

for simple bearer token patterns:

const BEARER_AUTH = createAuthSchemeConfig({
  mode: 'BEARER_TOKEN',
  strictFields: {
    headers: {
      bearer_token: {
        display_name: 'Bearer Token',
        description: 'Your bearer token',
        required: true,
        field_type: 'connection_field',
        is_secret: true,
        legacy_template_name: 'bearer_token',
      },
    },
  },
  name: 'bearer_token_auth',
})

dynamic configuration

dynamic base urls

when services require user-specific urls (subdomains, regions, etc.):

const DYNAMIC_OAUTH = createAuthSchemeConfig({
  mode: 'OAUTH2',
  strictFields: {
    baseUrl: {
      subdomain: {
        display_name: 'Workspace Subdomain',
        description:
          'Your workspace subdomain (e.g., "acme" for acme.example.com)',
        required: true,
        field_type: 'connection_field',
        is_secret: false,
        legacy_template_name: 'subdomain',
      },
      region: {
        display_name: 'Region',
        description: 'Your data center region',
        required: false,
        default: 'us-east-1',
        field_type: 'connection_field',
        is_secret: false,
        legacy_template_name: 'region',
      },
    },
    headers: {
      bearer_token: {
        display_name: 'Access Token',
        description: 'OAuth2 access token',
        required: false,
        field_type: 'auth_config_field',
        is_secret: false,
        legacy_template_name: 'access_token',
      },
    },
  },
  token_url: (fields) =>
    `https://${fields.baseUrl.subdomain}.api.example.com/oauth/token`,
  authorization_url: (fields) =>
    `https://${fields.baseUrl.subdomain}.api.example.com/oauth/authorize`,
  name: 'dynamic_oauth',
})

const config = createToolkitConfig({
  authSchemes: [DYNAMIC_OAUTH],
  baseUrl: (fields) => `https://${fields.subdomain}.api.example.com/v1`,
  name: 'Example Service',
  // ... other config
})

field access patterns

when using dynamic configuration, fields are accessible through namespaces:

// in auth scheme functions
headers: (fields) => ({
  Authorization: `Bearer ${fields.generic_api_key}`, // header field
  'X-Subdomain': fields.baseUrl.subdomain,           // baseUrl field
})

// in toolkit functions
baseUrl: (fields) =>
  `https://${fields.subdomain}.api.com`, // shared fields (available in all schemes)

get_current_user_endpoint: (fields) =>
  `https://${fields.subdomain}.api.com/user/me`,

toolkit configuration

complete toolkit configuration with all options:

const config = createToolkitConfig({
  authSchemes: [AUTH_SCHEME_1, AUTH_SCHEME_2], // multiple auth methods
  baseUrl: (fields) => `https://api.example.com/v1`,
  name: 'Example Service',
  logo: 'https://cdn.example.com/logo.svg',
  docs: 'https://docs.example.com/api',
  unique_key: 'example_service',
  categories: ['productivity', 'communication'],
  description: 'Powerful example service for productivity',
  app_url: 'https://example.com',
  get_current_user_endpoint: (fields) => `https://api.example.com/user/me`,
  status: 'active',
  disabled: false,
  run_in_sandbox: false,
})

configuration options

• authSchemes: array of authentication schemes
• baseUrl: base api url (function for dynamic urls)
• name: human-readable service name
• logo: service logo url
• docs: api documentation url
• unique_key: unique identifier for the service
• categories: service categories for organization
• description: brief service description
• app_url: main service website
• get_current_user_endpoint: endpoint to fetch current user info
• status: service status (optional)
• disabled: whether service is disabled
• run_in_sandbox: whether to run in sandboxed environment

field reference

field types

• connection_field: user-provided values (api keys, usernames, subdomains)
• auth_config_field: system-managed values (oauth tokens, generated credentials)

field properties

{
  display_name: 'User-friendly name shown in UI',
  description: 'Help text explaining what this field is for',
  required: true, // whether field is mandatory
  field_type: 'connection_field', // or 'auth_config_field'
  is_secret: true, // whether to mask value in UI
  default: 'default-value', // default value for optional fields
  legacy_template_name: 'old_name', // backwards compatibility
}

common field names

• generic_api_key: standard api key field
• bearer_token: oauth2 access token
• basic_encoded: base64 encoded basic auth
• username/password: basic auth credentials
• subdomain: workspace/tenant subdomain
• region: data center region

advanced patterns

multiple authentication methods

support both api key and oauth2:

const API_KEY_AUTH = createAuthSchemeConfig({
  mode: 'API_KEY',
  // ... config
  name: 'api_key_auth',
})

const OAUTH_AUTH = createAuthSchemeConfig({
  mode: 'OAUTH2',
  // ... config
  name: 'oauth_auth',
})

const config = createToolkitConfig({
  authSchemes: [API_KEY_AUTH, OAUTH_AUTH],
  // ... rest of config
})

complex oauth2 scopes

default_scopes: () => ['read:user', 'write:repo'],
scope_separator: ' ', // space-separated
available_scopes: [
  'read:user',
  'write:repo',
  'read:org',
  'admin:repo'
],
authorization_params: {
  response_type: 'code',
  access_type: 'offline',
  prompt: 'consent',
  include_granted_scopes: 'true',
},

custom request configuration

token_access_request_method: 'POST',
token_request_auth_method: 'request_body',
request_params: {
  format: 'json',
  version: 'v2',
},

refresh token configuration

For OAuth2 authentication, you can also configure how refresh token requests are handled:

refresh_access_request_method: 'POST', // HTTP method for refresh requests
refresh_request_auth_method: 'basic',   // Authentication method for refresh requests
refresh_params: {
  grant_type: 'refresh_token',
},

The refresh_request_auth_method supports the same values as token_request_auth_method:

• 'basic' - Uses Basic Authentication with client credentials
• 'request_body' - Includes client credentials in the request body

examples

simple api key service

import {
  createAuthSchemeConfig,
  createToolkitConfig,
} from '@composio/auth-config'

const API_KEY_AUTH = createAuthSchemeConfig({
  mode: 'API_KEY',
  strictFields: {
    headers: {
      generic_api_key: {
        display_name: 'API Key',
        description: 'Your API key from dashboard settings',
        required: true,
        field_type: 'connection_field',
        is_secret: true,
        legacy_template_name: 'api_key',
      },
    },
  },
  headers: (fields) => ({
    'X-API-Key': fields.generic_api_key,
  }),
  name: 'api_key_auth',
})

export default createToolkitConfig({
  authSchemes: [API_KEY_AUTH],
  baseUrl: () => 'https://api.simpleservice.com/v1',
  name: 'Simple Service',
  logo: 'https://simpleservice.com/logo.svg',
  unique_key: 'simple_service',
  categories: ['productivity'],
  description: 'Simple API service integration',
})

multi-tenant oauth2 service

import {
  createAuthSchemeConfig,
  createToolkitConfig,
} from '@composio/auth-config'

const OAUTH_AUTH = createAuthSchemeConfig({
  mode: 'OAUTH2',
  strictFields: {
    baseUrl: {
      subdomain: {
        display_name: 'Workspace Subdomain',
        description: 'Your workspace subdomain',
        required: true,
        field_type: 'connection_field',
        is_secret: false,
        legacy_template_name: 'subdomain',
      },
    },
    headers: {
      bearer_token: {
        display_name: 'Access Token',
        description: 'OAuth2 access token',
        required: false,
        field_type: 'auth_config_field',
        is_secret: false,
        legacy_template_name: 'access_token',
      },
    },
  },
  token_url: (fields) =>
    `https://${fields.baseUrl.subdomain}.multitenant.com/oauth/token`,
  authorization_url: (fields) =>
    `https://${fields.baseUrl.subdomain}.multitenant.com/oauth/authorize`,
  default_scopes: () => ['read', 'write'],
  scope_separator: ' ',
  name: 'oauth_auth',
})

export default createToolkitConfig({
  authSchemes: [OAUTH_AUTH],
  baseUrl: (fields) => `https://${fields.subdomain}.multitenant.com/api/v1`,
  get_current_user_endpoint: (fields) =>
    `https://${fields.subdomain}.multitenant.com/api/v1/user`,
  name: 'Multi-Tenant Service',
  logo: 'https://multitenant.com/logo.svg',
  unique_key: 'multitenant_service',
  categories: ['collaboration'],
  description: 'Multi-tenant collaborative platform',
})

troubleshooting

common issues

1. typescript errors: run bun run tsc --noEmit to check compilation
2. field not available: ensure fields are defined in strictFields
3. dynamic url errors: verify field names match between auth