Migration Guide

Upgrade guides for migrating between major versions of the WorkOS Node SDK

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.

v7

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

v7

// 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.

v7

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.

v7

// 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.

v7

// 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.

v7

await workos.mfa.verifyFactor({
  authenticationFactorId: 'auth_factor_123',
  code: '123456',
});

Organizations Changes

Organization Options

Removed fields:

• allowProfilesOutsideOrganization
• domains (use domainData instead)

v7

await workos.organizations.createOrganization({
  name: 'Acme Corp',
  domains: ['acme.com'],
  allowProfilesOutsideOrganization: true,
});

Vault Changes

Method Names

Changed: All *Secret methods renamed to *Object.

v7

// 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.

v7

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.

Node.js

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:

• Check the Changelog for detailed release notes
• Review the API Reference for updated method signatures
• Open an issue on GitHub
• Contact [e-mail]