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

February 14, 2026

v8.5.0

Latest

February 14, 2026

What's Changed

Add dedicated event types for organisation role deserialisation by @smorimoto in #1485

Version bump to 8.4.1 by @csrbarber in #1489

chore(deps): update actions/setup-node action to v6 by @renovate[bot] in #1444

chore(deps): update actions/checkout action to v6 by @renovate[bot] in #1390

v8.5.0 by @nicknisi in #1493

Full Changelog: v8.4.0...v8.5.0

February 13, 2026

v8.4.0

February 13, 2026

What's Changed

Added: Authorization Resource support by @swaroopAkkineniWorkos in #1479

Added: Role support by @swaroopAkkineniWorkos in #1479

Deprecated: FGA by @swaroopAkkineniWorkos in #1479

February 11, 2026

v8.3.1

February 11, 2026

What's Changed

Rename api_key.deleted event type to api_key.revoked by @smorimoto in #1476

New Contributors

@smorimoto made their first contribution in #1476

Full Changelog: v8.3.0...v8.3.1

February 10, 2026

v8.3.0

February 10, 2026

What's Changed

Organization role and permission events support by @csrbarber in #1469

Full Changelog: v8.2.0...v8.3.0

February 5, 2026

v8.2.0

February 5, 2026

What's Changed

feat: Add environment role support by @csrbarber in #1454

feat: Add organization role support by @csrbarber in #1455

Bump to 8.2.0 by @csrbarber in #1466

Full Changelog: v8.1.0...v8.2.0

February 3, 2026

v8.1.0

February 3, 2026

What's Changed

docs: fix inconsistencies in V8 migration guide by @nicknisi in #1449

Add custom_attributes field to OrganizationMembership by @ajworkos in #1458

feat: Add locale param to send/resend invitation methods by @jasonbarry in #1460

fix: exclude organizationId from autoPagination params in listOrganizationFeatureFlags by @gjtorikian in #1461

Release v8.1.0 by @gjtorikian in #1462

New Contributors

@jasonbarry made their first contribution in #1460

@gjtorikian made their first contribution in #1461

Full Changelog: v8.0.0...v8.1.0

January 12, 2026

v8.0.0

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.

✨ 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

🔥 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

⚠️ 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

v7.80.0 by @stanleyphu in #1436

Full Changelog: v7.79.3...v7.80.0

January 2, 2026

v7.79.3

January 2, 2026

What's Changed

Update qs by @gcarvelli in #1432

Full Changelog: v7.79.2...v7.79.3

December 30, 2026

v7.79.2

December 30, 2026

What's Changed

Fix URLs in package.json by @gcarvelli in #1428

Full Changelog: v7.79.1...v7.79.2

December 30, 2026

v7.79.1

December 30, 2026

What's Changed

Update repository.url to match npm expectation by @hexedpackets in #1426

Full Changelog: v7.79.0...v7.79.1

December 30, 2026

v7.79.0

December 30, 2026

What's Changed

Add readObjectByName method for Vault API by @hexedpackets in #1424

Full Changelog: v7.78.0...v7.79.0

December 24, 2025

v7.78.0

December 24, 2025

What's Changed

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