Skip to main content
This guide helps you migrate your code between major versions of the WorkOS Node SDK.

​
Migrating from v7 to v8

Version 8 is a major release focused on universal runtime compatibility, PKCE authentication support, and API modernization.

​
Update Requirements

​
Node.js Version

Change: Minimum Node.js version increased from 16 to 20. 
# Check your Node version
node --version

# Should be v20.15.0 or higher
Why: Node 18 reached end-of-life in April 2025.

​
Package Type

The package is now ESM-first with dual CJS/ESM exports. Most users won’t need changes, but custom build configurations may require adjustments.

​
Directory Sync Changes

​
DirectoryUser Interface

Changed: Removed top-level fields in favor of customAttributes. 
const user = await workos.directorySync.getUser({ userId });

console.log(user.emails);
console.log(user.username);
console.log(user.jobTitle);
Removed:
  • user.emails → Use user.customAttributes?.emails
  • user.username → Use user.customAttributes?.username
  • user.jobTitle → Use user.customAttributes?.jobTitle
  • getPrimaryEmail() utility function

​
User Management Changes

​
Removed Methods

// Old method names
await workos.userManagement.sendMagicAuthCode(options);
await workos.userManagement.sendPasswordResetEmail(options);
await workos.userManagement.refreshAndSealSessionData(options);

​
Authorization URL Options

Removed: The context field is no longer supported. 
const url = await workos.userManagement.getAuthorizationUrl({
  provider: 'authkit',
  redirectUri: 'https://example.com/callback',
  context: 'some-context', // No longer supported
});

​
List Organization Memberships

Changed: Now requires either userId or organizationId. 
// Could call without parameters
const memberships = await workos.userManagement.listOrganizationMemberships();

​
SSO Changes

​
Authorization URL Options Type

Changed: Converted to discriminated union for better type safety. 
// Multiple options allowed (unsafe)
const url = await workos.sso.getAuthorizationUrl({
  connection: 'conn_123',
  organization: 'org_456', // Both accepted
  redirectUri: 'https://example.com/callback',
});
Removed: The domain field (deprecated).

​
MFA Changes

​
Verify Factor Method

Changed: Method renamed for clarity. 
await workos.mfa.verifyFactor({
  authenticationFactorId: 'auth_factor_123',
  code: '123456',
});

​
Organizations Changes

​
Organization Options

Removed fields:
  • allowProfilesOutsideOrganization
  • domains (use domainData instead)
await workos.organizations.createOrganization({
  name: 'Acme Corp',
  domains: ['acme.com'],
  allowProfilesOutsideOrganization: true,
});

​
Vault Changes

​
Method Names

Changed: All *Secret methods renamed to *Object. 
// Old method names
await workos.vault.createSecret(options);
await workos.vault.listSecrets(options);
await workos.vault.readSecret(options);
await workos.vault.updateSecret(options);
await workos.vault.deleteSecret(options);

​
Events Changes

​
Event Types

Changed: Event type renamed. 
if (event.event === 'dsync.deactivated') {
  // Handle deactivation
}
Removed event types:
  • OrganizationMembershipAdded
  • OrganizationMembershipRemoved

​
New Features in v8

​
PKCE Authentication

Version 8 adds full support for PKCE authentication, enabling public clients. 
import { WorkOS } from '@workos-inc/node';

// Initialize without API key (public client)
const workos = new WorkOS({ clientId: 'client_123' });

// Generate authorization URL with PKCE
const { url, codeVerifier } = 
  await workos.userManagement.getAuthorizationUrlWithPKCE({
    provider: 'authkit',
    redirectUri: 'myapp://callback',
  });

// Exchange code for tokens
const { accessToken, refreshToken } = 
  await workos.userManagement.authenticateWithCode({
    code: authorizationCode,
    codeVerifier,
  });
See the User Management API and PKCE Flow guide for more details on PKCE authentication.

​
Type-Safe Client Modes

Use the createWorkOS() factory for compile-time type safety. 
import { createWorkOS } from '@workos-inc/node';

// Public client - only PKCE methods available
const publicClient = createWorkOS({ clientId: 'client_123' });
publicClient.userManagement.getAuthorizationUrlWithPKCE({ ... }); // ✅ Works
publicClient.userManagement.listUsers(); // ❌ TypeScript error

// Confidential client - full access
const serverClient = createWorkOS({ 
  apiKey: 'sk_...', 
  clientId: 'client_123' 
});
serverClient.userManagement.listUsers(); // ✅ Works

​
Universal Runtime Support

Version 8 works seamlessly across multiple JavaScript runtimes. 
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_...');

​
Migration Checklist

1

Update Node.js

Ensure you’re running Node.js 20.15.0 or higher.
node --version
2

Update Package

Update to the latest version of the SDK.
npm install @workos-inc/node@latest
3

Update Directory Sync

Replace user.emails, user.username, and user.jobTitle with user.customAttributes.*
4

Update User Management

  • Remove context from authorization URL options
  • Add userId or organizationId to listOrganizationMemberships()
  • Update deprecated method names
5

Update SSO

Ensure authorization URL options use only one of: connection, organization, or provider
6

Update MFA

Replace verifyFactor() with verifyChallenge()
7

Update Organizations

Replace domains with domainData and remove allowProfilesOutsideOrganization
8

Update Vault

Replace all *Secret methods with *Object methods
9

Update Events

Replace dsync.deactivated with dsync.deleted
10

Test Thoroughly

Run your test suite and verify all integrations work correctly.

​
Need Help?

If you encounter issues during migration:

Build docs developers (and LLMs) love

Get started for freeTalk to us