Node.js SDK

Installation

JavaScript

 npm install @workos-inc/node

Beta Versions

Certain WorkOS features may be available only in the beta version of the SDK. Beta versions have the -beta.* suffix, for example, 3.2.0-beta.1. For more information on how to use the beta versions, refer to the README in the GitHub repository.

Releases

January 12, 2026

v8.0.0

Latest

January 12, 2026

What's Changed

chore(deps): update jest monorepo by @renovate[bot] in #832

Release v8.0.0: Universal Runtime Support & API Modernization by @nicknisi in #1370

Breaking Change

This is a breaking change that drops support for Node 16 and Node 18.

:sparkles: New Features

PKCE Authentication for Public Clients • API key is now optional - initialize with just clientId for public client apps • New getAuthorizationUrlWithPKCE() method generates PKCE challenge internally • authenticateWithCode() auto-detects client mode (public vs confidential) • New createWorkOS() factory with compile-time type safety - TypeScript errors if you use server-only methods on public clients • Use case: Build mobile apps, desktop apps, SPAs with secure WorkOS auth without exposing API keys

Universal Runtime Support • SDK now works seamlessly across Node.js, Deno, Bun, and Cloudflare Workers • Runtime-specific exports automatically detected via package.json conditions • Dual build strategy: ESM unbundled (optimal tree-shaking), CJS inlines ESM-only deps • No more lib/node_modules/ issues that broke Electron packaging

Better TypeScript Types • SSO authorization options now use discriminated unions (must specify exactly one of: connection, organization, or provider) • Public vs confidential client types enforced at compile time • Improved type inference across the board

:fire: Most Exciting Changes

You can now build mobile/desktop apps with WorkOS - PKCE support means no backend proxy needed for client apps

Deploy to Cloudflare Workers/edge - Full edge runtime support with proper exports

Type-safe public clients - TypeScript catches security mistakes at compile time

Works everywhere - Node, Deno, Bun, Workers all tested and verified

:warning: Breaking Changes

Minimum Node.js version: 20+ (Node 16 and 18 both have reached EOL)

Removed deprecated methods: • Vault: createSecret() → use createObject() • Vault: listSecrets() → use listObjects() • Vault: readSecret() → use readObject() • Vault: updateSecret() → use updateObject() • Vault: deleteSecret() → use deleteObject() • MFA: verifyFactor() → use verifyChallenge() • User Management: sendMagicAuthCode() → use sendMagicCode()

API Changes: • listOrganizationMemberships() now requires userId OR organizationId • Directory Sync: user fields moved to customAttributes (e.g., user.customAttributes?.emails) • SSO: stricter types - must specify one of connection, organization, or provider (not multiple) • Organizations: removed allowProfilesOutsideOrganization and domains fields • Events: dsync.deactivated → dsync.deleted

Package structure: • Now ESM-first with dual CJS/ESM exports • Removed internal HTTP/crypto provider classes (public API unchanged)

• Install: npm install @workos-inc/node@8 • Migration Guide: V8_MIGRATION_GUIDE.md

Questions? Hit me up!

Full Changelog: v7.82.0...v8.0.0

January 9, 2026

v7.82.0

January 9, 2026

What's Changed

Add context field to Event interface by @nicknisi in #1442

Full Changelog: v7.81.0...v7.82.0

January 7, 2026

v7.81.0

January 7, 2026

What's Changed

Add api key events by @stanleyphu in #1437

v7.81.0 by @stanleyphu in #1438

Full Changelog: v7.80.0...v7.81.0

January 7, 2026

v7.80.0

January 7, 2026

What's Changed

Add Invitation Resent Event Interfaces by @kevinmitch14 in #1433

Add api keys management api methods by @stanleyphu in #1434

Add authenticationMethod to sealed session by @cmatheson in #1417

add context7.json to repo by @nicknisi in #1421

feat: enable npm Trusted Publishers by @nicknisi in #1422

Add support for feature flags management API by @stanleyphu in #1420

Full Changelog: v7.77.0...v7.78.0

December 4, 2025

v7.77.0

December 4, 2025

What's Changed

Add workos.pipes.getAccessToken by @dandorman in #1394

Full Changelog: v7.76.0...v7.77.0

December 3, 2025

v7.76.0

December 3, 2025

What's Changed

Add roles to directory user & profile by @kendallstrautman in #1401

Bump version to v7.76.0 by @kendallstrautman in #1410

Full Changelog: v7.75.1...v7.76.0

December 2, 2025

v7.75.1

December 2, 2025

What's Changed

Add randomUUID to CryptoProvider for edge runtime compatibility by @nicknisi in #1404

Full Changelog: v7.75.0...v7.75.1

December 1, 2025

v7.75.0

December 1, 2025

What's Changed

Add missing authentication methods by @cmatheson in #1405

November 24, 2025

v7.74.2

November 24, 2025

What's Changed

Export vault interfaces by @kendallstrautman in #1399

Bump 7.74.2 by @kendallstrautman in #1400

Full Changelog: v7.74.1...v7.74.2

November 21, 2025

v7.74.1

November 21, 2025

What's Changed

Expose interfaces for feature flags by @davidcornu in #1395

Update version to v7.74.1 by @stanleyphu in #1396

New Contributors

@davidcornu made their first contribution in #1395

Full Changelog: v7.74.0...v7.74.1

November 21, 2025

v7.74.0

November 21, 2025

What's Changed

Default to adding idempotecy-key to audit-logs/events if not present by @swaroopAkkineniWorkos in #1383

Add ability to resend invitation by @antn in #1387

Add passkey authentication events by @ericroberts in #1392

New Contributors

@swaroopAkkineniWorkos made their first contribution in #1383

Full Changelog: v7.73.0...v7.74.0

November 13, 2025

v7.73.0

November 13, 2025

Add argon2 to PasswordHashType interface

November 6, 2025

v8.0.0-rc.3

Pre-release

November 6, 2025

What's Changed

Remove dependency on pluralize by @lucasmotta in #1379

[v8] Replace leb and qs deps with vanilla implementations by @nicknisi in #1382

Full Changelog: v7.72.2...v8.0.0-rc.3

November 5, 2025

v7.72.2

November 5, 2025

What's Changed

Add api-keys widget scope by @ajworkos in #1377

v7.72.2 by @ajworkos in #1378

Full Changelog: v7.72.1...v7.72.2

October 29, 2025

v7.72.1

October 29, 2025

What's Changed

Use retryable HTTP requests for Vault API by @hexedpackets in #1375

Full Changelog: v7.72.0...v7.72.1

October 28, 2025

v7.72.0

October 28, 2025

What's Changed

Add apiKeys.validateApiKey method by @nholden in #1373

add convex conditional export by @erquhart in #1372

New Contributors

@erquhart made their first contribution in #1372

Full Changelog: v7.71.0...v7.72.0

October 15, 2025

v8.0.0-rc.1

Pre-release

October 15, 2025

What's Changed

Default PaginationOptions on AutoPaginatable by @nicknisi in #1369

[v8] Add runtime analytics to User-Agent string by @nicknisi in #1293

Full Changelog: v7.71.0...v8.0.0-rc.1

October 10, 2025

v7.71.0

October 10, 2025

What's Changed

Added Salesforce OAuth as an authentication provider (#1361)

Added locale to user (#1363)

Added GET /user_management/users/:id/feature-flags support (#1364)

Full Changelog: v7.70.0...v7.71.0

September 18, 2025

v7.70.0

September 18, 2025

What's Changed

Add multiple roles support by @csrbarber in #1358

Bump version to 7.70.0 by @csrbarber in #1359

New Contributors

@csrbarber made their first contribution in #1358

Full Changelog: v7.69.2...v7.70.0

September 3, 2025

v7.69.2

September 3, 2025

What's Changed

Fix GetTokenOptions[scopes] type by @chaance in #1348

Add timeout to WorkOSOptions for http client requests by @nave91 in #1351

v7.67.0

August 15, 2025

What's Changed

add widgets:sso:manage scope by @cmatheson in #1337

Full Changelog: v7.66.1...v7.67.0

August 11, 2025

v7.66.1

August 11, 2025

What's Changed

Fix feature flags endpoint URL by @nicknisi in #1335

Full Changelog: v7.66.0...v7.66.1