Configuration

Configure the WorkOS Node.js SDK with API keys, custom options, and runtime settings

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:

Environment Variables

.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();

String Parameter

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

const workos = new WorkOS('sk_test_1234567890');

Options Object

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

const workos = new WorkOS({
  apiKey: 'sk_test_1234567890',
  clientId: 'client_1234567890',
});

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:

Development

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