Node.js SDK

v9.3.0...v9.3.1" rel="noreferrer" target="_blank">9.3.1 (2026-05-19)

Bug Fixes

• set canonical User-Agent header format (https://github.com/workos/workos-node/issues/1576" rel="noreferrer" target="_blank">#1576) (https://github.com/workos/workos-node/commit/4169434bc9b59d77c3b226292441e8bad0a0df91" rel="noreferrer" target="_blank">4169434)
• webhooks: accept raw request bytes for signature verification (https://github.com/workos/workos-node/issues/1578" rel="noreferrer" target="_blank">#1578) (https://github.com/workos/workos-node/commit/112b261ecbfc68d0ee4912ad78095b1c70cf58b5" rel="noreferrer" target="_blank">112b261)

v9.2.0...v9.3.0" rel="noreferrer" target="_blank">9.3.0 (2026-05-13)

Features

• Add resource and role_slug filter params to list role assignments (https://github.com/workos/workos-node/issues/1585" rel="noreferrer" target="_blank">#1585) (https://github.com/workos/workos-node/commit/4f32a83c1b490ffe97ecdfb18dadee22061d93c8" rel="noreferrer" target="_blank">4f32a83)

v9.1.1...v9.2.0" rel="noreferrer" target="_blank">9.2.0 (2026-05-04)

Features

• Add resource role assignments methods (https://github.com/workos/workos-node/issues/1580" rel="noreferrer" target="_blank">#1580) (https://github.com/workos/workos-node/commit/ec8dd0f66e507f4fb9dfe3d13260eb5da7c8ba77" rel="noreferrer" target="_blank">ec8dd0f)

--- This PR was generated with Release Please. See documentation.

v9.1.0...v9.1.1" rel="noreferrer" target="_blank">9.1.1 (2026-04-24)

Bug Fixes

• Correctly handle all isAuthenticationErrorData cases (https://github.com/workos/workos-node/issues/1573" rel="noreferrer" target="_blank">#1573) (https://github.com/workos/workos-node/commit/b572431a9e225a8eb524220b054cef0596c7574b" rel="noreferrer" target="_blank">b572431)
• Fix incorrect url for listEffectivePermissionsByExternalId (https://github.com/workos/workos-node/issues/1574" rel="noreferrer" target="_blank">#1574) (https://github.com/workos/workos-node/commit/8f8fc8168f6fcf6109e99938ab36c588c3e9bf62" rel="noreferrer" target="_blank">8f8fc81)
• restore typed data on AuthenticationErrorData (https://github.com/workos/workos-node/issues/1570" rel="noreferrer" target="_blank">#1570) (https://github.com/workos/workos-node/commit/a7a1e6dee05d9449b4c565906536f67b343d0fd1" rel="noreferrer" target="_blank">a7a1e6d)
• revert "Rename Authorization methods to match oagen hints" (https://github.com/workos/workos-node/commit/7ab03806854349928bac91d3f014e37f33cf94cc" rel="noreferrer" target="_blank">7ab0380)

v9.0.0...v9.1.0" rel="noreferrer" target="_blank">9.1.0 (2026-04-21)

Features

• add support for role_slug in invitation schema (https://github.com/workos/workos-node/issues/1567" rel="noreferrer" target="_blank">#1567) (https://github.com/workos/workos-node/commit/ba29409743619ebb855c06b7c9987114afae61ea" rel="noreferrer" target="_blank">ba29409)

v8.13.0...v9.0.0" rel="noreferrer" target="_blank">9.0.0 (2026-04-21)

⚠ BREAKING CHANGES

• rename portal to adminPortal (https://github.com/workos/workos-node/issues/1562" rel="noreferrer" target="_blank">#1562)
• standardize authorization list endpoint pagination (https://github.com/workos/workos-node/issues/1553" rel="noreferrer" target="_blank">#1553)
• Drop Node.js v20 support, require v22.11+ (https://github.com/workos/workos-node/issues/1560" rel="noreferrer" target="_blank">#1560)
• Remove legacy FGA package (https://github.com/workos/workos-node/issues/1559" rel="noreferrer" target="_blank">#1559)

Features

• Add groups endpoints and group event types (https://github.com/workos/workos-node/issues/1564" rel="noreferrer" target="_blank">#1564) (https://github.com/workos/workos-node/commit/cb0c46d74304942146259c4b90778f05fc16df64" rel="noreferrer" target="_blank">cb0c46d)
• adding three new conection types to node SDK connection type enums (https://github.com/workos/workos-node/issues/1389" rel="noreferrer" target="_blank">#1389) (https://github.com/workos/workos-node/commit/c11cfd659f2a151b3e03e7db88feac1fac3a6483" rel="noreferrer" target="_blank">c11cfd6)
• standardize authorization list endpoint pagination (https://github.com/workos/workos-node/issues/1553" rel="noreferrer" target="_blank">#1553) (https://github.com/workos/workos-node/commit/7a91d74146c0b4464aefa0e046c7fc002464a8ee" rel="noreferrer" target="_blank">7a91d74)
• Update Node SDK to include auditlogs.listSchemas (https://github.com/workos/workos-node/issues/1457" rel="noreferrer" target="_blank">#1457) (https://github.com/workos/workos-node/commit/c31736df36c5c933628950e5be38ae542883116c" rel="noreferrer" target="_blank">c31736d)

Bug Fixes

• add JSDoc docstrings from OpenAPI spec to all resource methods (https://github.com/workos/workos-node/issues/1565" rel="noreferrer" target="_blank">#1565) (https://github.com/workos/workos-node/commit/562a57abfbabbb37c037fee53544c47df662cd57" rel="noreferrer" target="_blank">562a57a)
• errors: type server/auth errors and restore type compatibility (https://github.com/workos/workos-node/issues/1561" rel="noreferrer" target="_blank">#1561) (https://github.com/workos/workos-node/commit/e149152e873afd3ef9034c27a4505281bbadca9e" rel="noreferrer" target="_blank">e149152)
• Export ConflictException and add code (https://github.com/workos/workos-node/issues/1563" rel="noreferrer" target="_blank">#1563) (https://github.com/workos/workos-node/commit/a5524f8d567ea842297ef780d9fd11f3120ad7ce" rel="noreferrer" target="_blank">a5524f8)
• Normalize GithubOAuth to GitHubOAuth in identity deserialization (https://github.com/workos/workos-node/issues/1566" rel="noreferrer" target="_blank">#1566) (https://github.com/workos/workos-node/commit/61f54a544434d7af8ca2e93d742214c6fa776c6e" rel="noreferrer" target="_blank">61f54a5)
• Remove extractVersion from matchUpdateTypes rules (https://github.com/workos/workos-node/issues/1557" rel="noreferrer" target="_blank">#1557) (https://github.com/workos/workos-node/commit/f6272ea85ecf4fa72142a8a046a8df175c180f0a" rel="noreferrer" target="_blank">f6272ea)
• rename portal to adminPortal (https://github.com/workos/workos-node/issues/1562" rel="noreferrer" target="_blank">#1562) (https://github.com/workos/workos-node/commit/80614d470ea43d11f76824db4390726fba041002" rel="noreferrer" target="_blank">80614d4)

Code Refactoring

• Drop Node.js v20 support, require v22.11+ (https://github.com/workos/workos-node/issues/1560" rel="noreferrer" target="_blank">#1560) (https://github.com/workos/workos-node/commit/24609a737cb26d159774dd89ffca384cbc6c6723" rel="noreferrer" target="_blank">24609a7)
• Remove legacy FGA package (https://github.com/workos/workos-node/issues/1559" rel="noreferrer" target="_blank">#1559) (https://github.com/workos/workos-node/commit/8cdd668949d0b04e3b3eaf3214153d58ca16b0b1" rel="noreferrer" target="_blank">8cdd668)

Read the https://github.com/workos/workos-node/blob/main/docs/V9_MIGRATION_GUIDE.md" rel="noreferrer" target="_blank">V9_MIGRATION_GUIDE.md for more information.

v8.12.1...v8.13.0" rel="noreferrer" target="_blank">8.13.0 (2026-04-13)

Features

• Add resource_type_slug to createOrganizationRole to create resource-scoped custom roles (https://github.com/workos/workos-node/issues/1549" rel="noreferrer" target="_blank">#1549) (https://github.com/workos/workos-node/commit/36fb14a81884892ba325a9d8a3f2b8e1c9023b58" rel="noreferrer" target="_blank">36fb14a)

v8.12.0...v8.12.1" rel="noreferrer" target="_blank">8.12.1 (2026-04-07)

Bug Fixes

• events: handle domain verification failed (https://github.com/workos/workos-node/issues/1543" rel="noreferrer" target="_blank">#1543) (https://github.com/workos/workos-node/commit/0f3f1ceef4a6da35ce3caf434835f0ec0ae2b827" rel="noreferrer" target="_blank">0f3f1ce)

v8.11.1...v8.12.0" rel="noreferrer" target="_blank">8.12.0 (2026-04-06)

Features

• Add vault.byok_key.verification_completed event interface (https://github.com/workos/workos-node/issues/1544" rel="noreferrer" target="_blank">#1544) (https://github.com/workos/workos-node/commit/5b29d3c0c961ca79b4dde30f8d95821847942c65" rel="noreferrer" target="_blank">5b29d3c)

v8.11.0...v8.11.1" rel="noreferrer" target="_blank">8.11.1 (2026-04-04)

Bug Fixes

• replace node:events with eventemitter3 in runtime client (https://github.com/workos/workos-node/issues/1540" rel="noreferrer" target="_blank">#1540) (https://github.com/workos/workos-node/commit/e293be1328cecbdee6107d86252341de0f387692" rel="noreferrer" target="_blank">e293be1)

v8.10.0...v8.11.0" rel="noreferrer" target="_blank">8.11.0 (2026-04-02)

Features

• Adds feature flags runtime client with local evaluation (https://github.com/workos/workos-node/issues/1511" rel="noreferrer" target="_blank">#1511) (https://github.com/workos/workos-node/commit/581c6182bc18384ba9912f681d76acb19d5964a2" rel="noreferrer" target="_blank">581c618)

Bug Fixes

• security: resolve miniflare and undici vulnerabilities (https://github.com/workos/workos-node/issues/1500" rel="noreferrer" target="_blank">#1500) (https://github.com/workos/workos-node/commit/cd6ddd017090786cc7b17b1398b1049201121fce" rel="noreferrer" target="_blank">cd6ddd0)

v8.9.0...v8.10.0" rel="noreferrer" target="_blank">8.10.0 (2026-03-25)

Features

• add vault events (https://github.com/workos/workos-node/issues/1531" rel="noreferrer" target="_blank">#1531) (https://github.com/workos/workos-node/commit/a5e619f7aa31b5c93054bd5a0eeba37d1f052f52" rel="noreferrer" target="_blank">a5e619f)

Bug Fixes

• correct typecheck issues (https://github.com/workos/workos-node/issues/1526" rel="noreferrer" target="_blank">#1526) (https://github.com/workos/workos-node/commit/5e52f6c72b503873f92b57b941e6b587d6e1c872" rel="noreferrer" target="_blank">5e52f6c)
• CreateAuthorizationResourceOptions type definition (https://github.com/workos/workos-node/issues/1530" rel="noreferrer" target="_blank">#1530) (https://github.com/workos/workos-node/commit/be2ec40abbc57a170b6b20f48d8e01e1258ec8f0" rel="noreferrer" target="_blank">be2ec40)
• events: add missing order parameter to listEvents (https://github.com/workos/workos-node/issues/1524" rel="noreferrer" target="_blank">#1524) (https://github.com/workos/workos-node/commit/2f3dcb4688bae519d114cc573cd5bf8da1bd0fd6" rel="noreferrer" target="_blank">2f3dcb4)
• vault: forward order and before params in listObjects (https://github.com/workos/workos-node/issues/1527" rel="noreferrer" target="_blank">#1527) (https://github.com/workos/workos-node/commit/2f9c2f19c2a31150745c47b504b83d86593a087b" rel="noreferrer" target="_blank">2f9c2f1)

v8.8.0...v8.9.0" rel="noreferrer" target="_blank">8.9.0 (2026-03-12)

Features

• user-management: add claimNonce to getAuthorizationUrl (https://github.com/workos/workos-node/issues/1518" rel="noreferrer" target="_blank">#1518) (https://github.com/workos/workos-node/commit/19e4a20e7db39a1fb5546229596cfaaa851907c2" rel="noreferrer" target="_blank">19e4a20)
• user-management: add directoryManaged to OrganizationMembership (https://github.com/workos/workos-node/issues/1512" rel="noreferrer" target="_blank">#1512) (https://github.com/workos/workos-node/commit/4594f4e2a871e94d719312bf0500f4d106169ed7" rel="noreferrer" target="_blank">4594f4e)

Bug Fixes

• Bump minimatch from 3.1.2 to 3.1.5 (https://github.com/workos/workos-node/issues/1507" rel="noreferrer" target="_blank">#1507) (https://github.com/workos/workos-node/commit/fe74c3342a0cbd61d265c1ddd5dd02a5a21eb371" rel="noreferrer" target="_blank">fe74c33)
• preserve sso context in authentication event deserialisation (https://github.com/workos/workos-node/issues/1487" rel="noreferrer" target="_blank">#1487) (https://github.com/workos/workos-node/commit/2bad11ca72127677fddfd2ae490a98cb77c53655" rel="noreferrer" target="_blank">2bad11c)
• preserve verification_prefix in organization domain deserialization (https://github.com/workos/workos-node/issues/1486" rel="noreferrer" target="_blank">#1486) (https://github.com/workos/workos-node/commit/640f0e419712755ce0e1f68dd3f441ce1282a75a" rel="noreferrer" target="_blank">640f0e4)

v8.7.0...v8.8.0" rel="noreferrer" target="_blank">8.8.0 (2026-03-03)

Features

• add missing auth methods (https://github.com/workos/workos-node/issues/1509" rel="noreferrer" target="_blank">#1509) (https://github.com/workos/workos-node/commit/3a5ce41949d09de38a6aa9c919617267c83714a0" rel="noreferrer" target="_blank">3a5ce41)

Bug Fixes

• export CookieSession from package root (https://github.com/workos/workos-node/issues/1504" rel="noreferrer" target="_blank">#1504) (https://github.com/workos/workos-node/commit/29048e992a08f32d353b38f2c53346ca3f39a16e" rel="noreferrer" target="_blank">29048e9)

v8.6.0...v8.7.0" rel="noreferrer" target="_blank">8.7.0 (2026-02-26)

Features

• add resourceTypeSlug to permissions, environment and organization roles (https://github.com/workos/workos-node/issues/1502" rel="noreferrer" target="_blank">#1502) (https://github.com/workos/workos-node/commit/74dadc6310412e4f3601d1ba90d3fc2d8fabde0a" rel="noreferrer" target="_blank">74dadc6)
• Add deserialisation support for feature flag events (https://github.com/workos/workos-node/issues/1494" rel="noreferrer" target="_blank">#1494) (https://github.com/workos/workos-node/commit/36214248128c1414bebceda634dc39689c296368" rel="noreferrer" target="_blank">3621424)

Bug Fixes

• update release-please manifest to match actual version 8.6.0 (https://github.com/workos/workos-node/issues/1503" rel="noreferrer" target="_blank">#1503) (https://github.com/workos/workos-node/commit/6814a5c75c12bbe02ed7db32ca8eb84c080b5d98" rel="noreferrer" target="_blank">6814a5c)

• Add BYOK intent to Admin Portal

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

What's Changed

• Added: Authorization Resource support by @swaroopAkkineniWorkos in #1479
• Added: Role support by @swaroopAkkineniWorkos in #1479
• Deprecated: FGA by @swaroopAkkineniWorkos in #1479

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

What's Changed

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

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

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

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

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_

1. _You can now build mobile/desktop apps with WorkOS_ - PKCE support means no backend proxy needed for client apps
2. _Deploy to Cloudflare Workers/edge_ - Full edge runtime support with proper exports
3. _Type-safe public clients_ - TypeScript catches security mistakes at compile time
4. _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_: https://github.com/workos/workos-node/blob/main/docs/V8_MIGRATION_GUIDE.md" rel="noreferrer" target="_blank">V8_MIGRATION_GUIDE.md

Questions? Hit me up!

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

What's Changed

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

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

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

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

What's Changed

• Update qs by @gcarvelli in #1432

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

What's Changed

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

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

What's Changed

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

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

What's Changed

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

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