Migration: V2 to V3 JS SDK

V3 introduces a modernized, promise-based SDK architecture that simplifies setup, improves security, and gives you more control over the authentication experience. This guide covers the key changes and provides a compatibility matrix for planning your migration.

What Changed

Area	V2	V3
Architecture	Single global object with callback-only patterns	Instance-based with promise + callback support
Initialization	new LoginRadiusV2(options) + separate LRObject.init() per action	new LoginRadiusSDK(options) with .init(action, options) per component
Theming	Manual CSS	Default brand theme from Admin Console via templateName / styleName
Localization	Hook-based (customizeFormLabel, customizeFormPlaceholder)	Built-in via localizationConfig + automatic browser language detection
Hook system	20+ global hooks	Scoped hooks per instance (async-ready)
Captcha	Per-provider config (v2RecaptchaSiteKey, invisibleRecaptcha)	Unified captchaLanguage across all providers

Initialization

V2

<script src="https://auth.lrcontent.com/v2/js/LoginRadiusV2.js"></script>
<script>
  var commonOptions = { apiKey: 'YOUR_API_KEY', appName: 'YOUR_APP_NAME' };
  var LRObject = new LoginRadiusV2(commonOptions);

  LRObject.$hooks.register('startProcess', function (name) { });
  LRObject.$hooks.register('endProcess', function (name) { });

  LRObject.util.ready(function () {
    LRObject.init('login', {
      container: 'login-container',
      onSuccess: function (response) { },
      onError: function (errors) { },
    });
  });
</script>

V3

<script src="https://auth.lrcontent.com/v2/LoginRadiusV3.js"></script>
<script>
  var LRObject = new LoginRadiusSDK({
    apiKey: 'YOUR_API_KEY',
    sott: 'YOUR_SOTT',
    callbackUrl: window.location.href.split('?')[0],
  });

  LRObject.init('login', {
    container: 'login-container',
    onSuccess: function (response) { },
    onError: function (error) { },
  });
</script>

Key differences:

• appName is no longer required — the SDK resolves it automatically from the domain
• sott is now passed in the constructor (not generated separately)
• No util.ready() wrapper needed — the SDK handles initialization timing
• Hooks are registered with LRObject.$hooks.call() instead of LRObject.$hooks.register()

Common Options Changes

New Options in V3

Option	Description
templateName	Applies a configured brand from the Admin Console with its default styles
styleName	Selects a style variation within a brand template
disableLocalization	Disables automatic browser-based language detection
localizationConfig	Custom label/message overrides as an object
captchaLanguage	Unified CAPTCHA localization across all providers (e.g., 'de' for German)
successMessageConfig	Configure success message UI: { messageType: 'toast' | 'container' | 'none', duration: 3200 }
errorMessageConfig	Configure error message UI: { messageType: 'toast' | 'container' | 'none', duration: 3200 }

Renamed Options

V2	V3	Notes
v2RecaptchaLanguage	captchaLanguage	Now applies to all CAPTCHA providers, not just reCAPTCHA v2

Removed Options

These options are either handled internally by V3 or planned for future releases:

Option	V3 Status
appName	Removed — resolved automatically from the domain URL
hashTemplate	Planned for a future release
debugMode	Planned for a future release
formValidationMessage	Planned — use localizationConfig.mapValidationMessages instead
passwordLength	Planned for a future release
twoFactorAuthentication	Planned — MFA is configured via Admin Console
stayLogin	Planned for a future release
displayPasswordStrength	Planned for a future release
tokenExpire	Planned for a future release
tokenType	Planned for a future release

Compatible Options (No Changes)

These options work identically in V2 and V3:

apiKey, sott, callbackUrl, verificationUrl, callbackType, customDomain, apiCustomDomain, v2Recaptcha, isMobile, projectionFields, resetPasswordUrl, and all smsTemplate* / email template options.

Init Actions

New Actions in V3

Action	Description
auth	Unified login + registration in a single component with tab switching
workflow	Identity Orchestration workflow execution — pass clientId and workflowName
orgInvite	B2B invitation acceptance flow

Renamed Actions

V2	V3	Notes
verifyEmail	verifyToken	Renamed for consistency — functionality is identical

Compatible Actions

Action	Notes
login	V3 includes a default theme, built-in Forgot Password link, and social login
registration	V3 includes a default theme, passkey registration support, and SSO
forgotPassword	V3 includes a default theme
passwordlessLogin	V3 includes a default theme
profileEditor	V3 includes Add Email, Add PIN, Change Password, Unlink Social. New logoutRedirectUrl option

Actions Not Yet in V3

These actions are being reintroduced in upcoming V3 releases. Where noted, functionality may be available through other actions:

V2 Action	V3 Workaround
changePassword	Available inside profileEditor
addEmail / removeEmail	Available inside profileEditor
createTwoFactorAuthentication	MFA is available via login and passwordlessLogin
changePin	Available inside profileEditor
socialLogin	Social login is built into login and auth
resetPassword	Planned for a future release
deleteUser / deleteUserConfirm	Planned for a future release
updatePhone	Planned for a future release
onetouchLogin	Planned for a future release
smartLogin	Planned for a future release
linkAccount / unLinkAccount	Planned for a future release

Hooks

V2 Hook Registration

LRObject.$hooks.register('startProcess', function (name) { });
LRObject.$hooks.register('customizeFormLabel', { emailid: 'Work Email' });
LRObject.$hooks.register('formValidationRules', { emailid: 'required|valid_email' });

V3 Hook Registration

LRObject.$hooks.call('mapErrorMessages', [
  { code: 936, message: 'Custom error for code 936' },
]);

LRObject.$hooks.call('mapValidationMessages', [
  { rule: 'required', message: 'This field is required' },
]);

Currently Supported Hooks in V3

Hook	Description
mapErrorMessages	Override error messages by API error code
mapValidationMessages	Override form validation messages by rule name

Hooks Not Yet in V3

Label, placeholder, and form customization hooks (customizeFormLabel, customizeFormPlaceholder, setButtonsName, formValidationRules, etc.) are planned for reintroduction. In the meantime, use localizationConfig in common options for label overrides.

Lifecycle hooks (startProcess, endProcess, afterFormRender, successCallback) are planned for reintroduction with async support.

Advanced Features

Compatible in V3

Feature	Notes
Risk Based Authentication (RBA)	Works the same — configure RBA templates via common options
Profile Editor	Enhanced with Add Email, Add PIN, Change Password, Unlink Social
Email Template Customizations	Same template options in common options
Projection of Fields	Same projectionFields option

Not Yet in V3

Feature	Notes
Progressive Profiling	Planned for a future release
Account Linking (standalone)	Available via profileEditor; standalone action planned
Security Questions	Planned for a future release
Smart Login	Planned for a future release
Get JWT Token	Planned for a future release

Step-by-Step Migration

1. Update the script tag — replace LoginRadiusV2.js with LoginRadiusV3.js (or install @loginradius/loginradius-js via npm)
2. Update initialization — change new LoginRadiusV2(options) to new LoginRadiusSDK(options), remove appName, add sott
3. Remove util.ready() wrappers — call init() directly
4. Update hook registration — change $hooks.register() to $hooks.call(), migrate to mapErrorMessages / mapValidationMessages
5. Rename actions — change verifyEmail to verifyToken
6. Replace removed options — move label customizations to localizationConfig, remove appName
7. Test — verify login, registration, MFA, profile, and any custom workflows
8. Consider new features — use auth for unified login/registration, workflow for Identity Orchestration, templateName for Admin Console branding

Related Resources

JS SDK OverviewJS SDK Getting StartedJS Legacy