Skip to main content
The WorkOS SDK provides flexible configuration options to customize its behavior for your application.

​
Basic configuration

The simplest way to configure the WorkOS client is by providing an API key:
.env
WORKOS_API_KEY="sk_test_1234567890"
WORKOS_CLIENT_ID="client_1234567890"

import { WorkOS } from '@workos-inc/node';

// Automatically reads from environment variables
const workos = new WorkOS();

​
Configuration options

The WorkOSOptions interface supports the following configuration parameters:

​
API credentials

​
apiKey
string
Your WorkOS API key from the dashboard. Required for server-side applications.
const workos = new WorkOS({
  apiKey: 'sk_test_1234567890',
});
​
clientId
string
Your WorkOS client ID. Required for authentication flows.
const workos = new WorkOS({
  apiKey: 'sk_test_1234567890',
  clientId: 'client_1234567890',
});

​
Network configuration

​
apiHostname
string
default:"api.workos.com"
Custom API hostname for self-hosted or regional deployments.
const workos = new WorkOS({
  apiKey: 'sk_test_1234567890',
  apiHostname: 'api.eu.workos.com',
});
​
https
boolean
default:"true"
Whether to use HTTPS protocol. Set to false for local development.
const workos = new WorkOS({
  apiKey: 'sk_test_1234567890',
  https: false,
  port: 3000,
});
​
port
number
Custom port for API requests. Useful for local development or proxy setups.
const workos = new WorkOS({
  apiKey: 'sk_test_1234567890',
  port: 8080,
});
​
timeout
number
Request timeout in milliseconds.
const workos = new WorkOS({
  apiKey: 'sk_test_1234567890',
  timeout: 10000, // 10 seconds
});

​
Advanced options

​
config
RequestInit
Additional fetch configuration options (headers, signal, etc.).
const workos = new WorkOS({
  apiKey: 'sk_test_1234567890',
  config: {
    headers: {
      'X-Custom-Header': 'value',
    },
  },
});
​
appInfo
object
Application metadata for tracking and debugging.
const workos = new WorkOS({
  apiKey: 'sk_test_1234567890',
  appInfo: {
    name: 'MyApp',
    version: '1.0.0',
  },
});
This information is included in the User-Agent header for all requests.
​
fetchFn
typeof fetch
Custom fetch implementation. Useful for testing or proxying requests.
const workos = new WorkOS({
  apiKey: 'sk_test_1234567890',
  fetchFn: customFetch,
});

​
Public client configuration

For applications that cannot securely store an API key (mobile apps, CLI tools, browser apps), initialize with only a client ID: 
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS({
  clientId: 'client_1234567890',
  // No apiKey required
});
Public clients can only use PKCE-based authentication methods. Server-side methods requiring an API key will throw an error.

​
Type-safe factory function

For compile-time type safety, use the createWorkOS factory function: 
import { createWorkOS } from '@workos-inc/node';

// Public client - TypeScript enforces PKCE-only methods
const publicWorkos = createWorkOS({
  clientId: 'client_123',
});

// TypeScript allows this
await publicWorkos.userManagement.getAuthorizationUrlWithPKCE({...});

// TypeScript error - listUsers requires API key
await publicWorkos.userManagement.listUsers(); // ❌ Error!

// Confidential client - full access
const workos = createWorkOS({
  apiKey: process.env.WORKOS_API_KEY!,
  clientId: 'client_123',
});

// Both methods work
await workos.userManagement.listUsers(); // ✅ OK
The createWorkOS factory function does not read from environment variables. Pass credentials explicitly for predictable type inference.

​
Environment-specific configuration

Configure the SDK differently for development, staging, and production: 
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
  // Use local development settings
  https: false,
  port: 3000,
  timeout: 30000, // Longer timeout for debugging
});

​
Custom headers

Add custom headers to all API requests: 
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS({
  apiKey: 'sk_test_1234567890',
  config: {
    headers: {
      'X-Custom-Header': 'value',
      'X-Request-ID': 'unique-request-id',
    },
  },
});
Custom headers are merged with default headers. The SDK automatically adds User-Agent and Authorization headers.

​
PKCE with confidential clients

Server-side applications can use PKCE alongside the client secret for enhanced security (recommended by OAuth 2.1): 
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_test_1234567890');

// Use PKCE even with API key for additional security
const { url, codeVerifier } = 
  await workos.userManagement.getAuthorizationUrlWithPKCE({
    provider: 'authkit',
    redirectUri: 'https://example.com/callback',
    clientId: workos.clientId!,
  });

// Both client_secret AND code_verifier will be sent
const { accessToken } = await workos.userManagement.authenticateWithCode({
  code: authorizationCode,
  codeVerifier,
  clientId: workos.clientId!,
});

​
Checking the SDK version

You can check which version of the SDK is running: 
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS();

console.log('WorkOS SDK version:', workos.version);

​
Next steps

Quickstart

Build your first integration with WorkOS

User Management

Set up authentication and user management

SSO Integration

Configure Single Sign-On

Webhooks

Handle WorkOS webhook events

Build docs developers (and LLMs) love

Get started for freeTalk to us