@composio/auth-config
Advanced tools
typed authentication configurations for integrations with full TypeScript support, validation, and automatic processing.
typed authentication configurations for integrations with full TypeScript support, validation, and automatic processing.
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.
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
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',
})
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',
})
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',
})
token_url: endpoint for exchanging codes for tokensrefresh_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 authorizationdefault_scopes: default permissions requestedscope_separator: separator for multiple scopes (usually space or comma)authorization_params: additional parameters for auth requeststoken_params: additional parameters for token requeststoken_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 requestsdisable_pkce: disable PKCE for older oauth2 implementationsfor 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',
})
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',
})
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
})
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`,
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,
})
authSchemes: array of authentication schemesbaseUrl: base api url (function for dynamic urls)name: human-readable service namelogo: service logo urldocs: api documentation urlunique_key: unique identifier for the servicecategories: service categories for organizationdescription: brief service descriptionapp_url: main service websiteget_current_user_endpoint: endpoint to fetch current user infostatus: service status (optional)disabled: whether service is disabledrun_in_sandbox: whether to run in sandboxed environmentconnection_field: user-provided values (api keys, usernames, subdomains)auth_config_field: system-managed values (oauth tokens, generated credentials){
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
}
generic_api_key: standard api key fieldbearer_token: oauth2 access tokenbasic_encoded: base64 encoded basic authusername/password: basic auth credentialssubdomain: workspace/tenant subdomainregion: data center regionsupport 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
})
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',
},
token_access_request_method: 'POST',
token_request_auth_method: 'request_body',
request_params: {
format: 'json',
version: 'v2',
},
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 bodyimport {
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',
})
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',
})
bun run tsc --noEmit to check compilationstrictFieldsFAQs
typed authentication configurations for integrations with full TypeScript support, validation, and automatic processing.
The npm package @composio/auth-config receives a total of 1,599 weekly downloads. As such, @composio/auth-config popularity was classified as popular.
We found that @composio/auth-config demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 6 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.
Security News
This episode explores the hard problem of reachability analysis, from static analysis limits to handling dynamic languages and massive dependency trees.
Security News
/Research
Malicious Nx npm versions stole secrets and wallet info using AI CLI tools; Socket’s AI scanner detected the supply chain attack and flagged the malware.