Documentation Index
Fetch the complete documentation index at: https://mintlify.com/workos/workos-node/llms.txt
Use this file to discover all available pages before exploring further.
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
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);
user.emails → Use user.customAttributes?.emailsuser.username → Use user.customAttributes?.usernameuser.jobTitle → Use user.customAttributes?.jobTitlegetPrimaryEmail() 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',
});
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:
allowProfilesOutsideOrganizationdomains (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
}
OrganizationMembershipAddedOrganizationMembershipRemoved
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,
});
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
Update Node.js
Ensure you’re running Node.js 20.15.0 or higher. Update Package
Update to the latest version of the SDK.npm install @workos-inc/node@latest
Update Directory Sync
Replace user.emails, user.username, and user.jobTitle with user.customAttributes.*
Update User Management
- Remove
context from authorization URL options
- Add
userId or organizationId to listOrganizationMemberships()
- Update deprecated method names
Update SSO
Ensure authorization URL options use only one of: connection, organization, or provider
Update MFA
Replace verifyFactor() with verifyChallenge()
Update Organizations
Replace domains with domainData and remove allowProfilesOutsideOrganization
Update Vault
Replace all *Secret methods with *Object methods
Update Events
Replace dsync.deactivated with dsync.deleted
Test Thoroughly
Run your test suite and verify all integrations work correctly.
Need Help?
If you encounter issues during migration: