Options

The options object is passed once when you instantiate the SDK and controls global behavior across all authentication flows. It covers core settings, transactional email/SMS templates, localization, theming, CAPTCHA, and UI messaging.

The fields documented here apply to both the LoginRadius JavaScript SDK and the LoginRadius React SDK — in the React SDK they are passed via the options prop on LoginRadiusProvider.

Configuration

Instantiate the SDK once at app startup and pass the credentials and any overrides you need. The minimum required field is apiKey.

const LRObject = new LoginRadiusSDK({
  apiKey: "<YOUR_API_KEY>", // required
  verificationUrl: "https://yourdomain.com/verify",
  resetPasswordUrl: "https://yourdomain.com/reset-password",
});

note

Enable CAPTCHA in the LoginRadius Dashboard before going live. CAPTCHA protects your authentication flows from automated abuse — turn on CAPTCHA from Console by navigating to Security → Attack Protection → Bot Protection.

Reference

The table below lists every field the SDK accepts.

note

Only apiKey is required at instantiation. sott is conditional — needed for registration only when Bot Protection (Captcha) is not enabled in the Admin Console (see the sott row for details). Every other field is optional and falls back to the documented default or your Admin Console configuration.

Option	Type	Description
`apiKey`	`string`	Your LoginRadius API key — the primary identifier for your application, required for all SDK operations.
`sott`	`string`	Secure One-Time Token that authorizes registration from the browser. Required only when Bot Protection (Captcha) is not enabled in the Admin Console — when Captcha is on, omit `sott`. Generate the token from Tenant Settings → API Configuration → SOTT, inject it server-side at page render, and never hardcode it in client bundles.
`verificationUrl`	`string`	The URL that LoginRadius sends email verification links to. The SDK appends the verification token as a query parameter.
`callbackUrl`	`string`	The URL the Hub redirects back to after social login. Defaults to `window.location.href` (stripped of query parameters) on SDK initialization.
`callbackInsideSameWindow`	`boolean`	Controls whether social login opens a popup window (`false`, default) or navigates the current tab to the provider (`true`). See Social login callback options below. Defaults to `false`.
`callbackType`	`'' \| 'hash' \| 'querystring'`	Controls how the social login token is delivered back to your app. Works together with `callbackInsideSameWindow`. See Social login callback options below. Defaults to `''`.
`resetPasswordUrl`	`string`	The URL included in password reset emails. LoginRadius appends a reset token to this URL.
`customDomain`	`string`	Override the default LoginRadius CDN domain with a custom domain configured in your Admin Console. Useful for white-label deployments.
`apiCustomDomain`	`string`	Override the default LoginRadius API domain. Use this when your environment routes API traffic through a custom domain or reverse proxy.
`projectionFields`	`string[]`	Specify which user profile fields the API returns. Reduces payload size and limits exposure of unnecessary profile data — recommended as a least-privilege practice.
`isMobile`	`boolean`	Signals to the SDK that it is rendering in a mobile context, adjusting certain UI behaviors and form interactions accordingly. Defaults to `false`.
`enableIdentifierCheck`	`boolean`	Enables an Identifier Availability check during the Register flow, so the chosen identifier (email, username, or phone) is verified as available before registration proceeds. The check is not mandatory. When `false` or omitted, the check is skipped and users can register without verifying identifier availability. Defaults to `false`.
`templateName`	`string`	Specifies a brand configured in the Admin Console. The SDK automatically retrieves and applies the default styles associated with that brand — no manual CSS import required.
`styleName`	`string`	Applies a specific style variant within the brand defined by `templateName` (which is required). The style must be configured (but not necessarily deployed) in the Admin Console.
`disableLocalization`	`boolean`	The SDK detects the browser's language and applies the corresponding locale automatically. Set to `true` to disable browser-based localization and enforce a fixed language. Defaults to `false`.
`localizationConfig`	`object`	Override the SDK's default text — labels, placeholders, validation messages, and button text. See Localization for details.
`captchaLanguage`	`string`	Applies a language locale to all CAPTCHA providers configured in the Admin Console (reCAPTCHA v2, reCAPTCHA v3, hCaptcha). Accepts standard BCP 47 language codes. Replaces the V2 `v2RecaptchaLanguage` parameter.
`v2Recaptcha`	`boolean`	Enables Google reCAPTCHA v2 on forms (must first be enabled in the Admin Console). By default reCAPTCHA v2 loads in invisible mode; set to `true` to render the visible checkbox widget. Defaults to `false`.
`successMessageConfig`	`object`	Controls how success messages are displayed after form actions. See successMessageConfig below.
`errorMessageConfig`	`object`	Controls how error messages are displayed when form actions fail. See errorMessageConfig below.
`resendRestriction`	`object`	Sets a per-flow cooldown timer (in seconds) on the resend button across components. After a resend click, the button is disabled and shows a countdown, then reactivates when the timer elapses. See resendRestriction below.
`contactusUrl`	`string`	A URL linked from certain error states to direct users to your support or contact page.
`formValidationMode`	`'onChange' \| 'onBlur'`	Controls when inline validation errors appear as users fill out SDK forms. See formValidationMode below. Defaults to `'onBlur'`.
`verificationEmailTemplate`	`string`	Template name for email address verification messages.
`welcomeEmailTemplate`	`string`	Template name for the email sent to users upon successful registration.
`resetPasswordEmailTemplate`	`string`	Template name for password reset request emails.
`resetPasswordConfirmationEmailTemplate`	`string`	Template name for the email sent after a password reset is completed.
`addEmailTemplate`	`string`	Template name for adding a secondary email address.
`deleteUserEmailTemplate`	`string`	Template name for the email sent when an account deletion is requested.
`onetouchLoginEmailTemplate`	`string`	Template name for one-touch (magic link) login emails.
`passwordlessLoginEmailTemplate`	`string`	Template name for passwordless login via email link.
`passwordlessLoginSMSTemplate`	`string`	Template name for passwordless login via SMS OTP.
`smsTemplate2FA`	`string`	Template name for two-factor authentication SMS OTP.
`smsTemplate2FAWelcome`	`string`	Template name for the welcome SMS sent after 2FA enrollment.
`smsTemplatePhoneVerification`	`string`	Template name for phone number verification SMS.
`smsTemplateWelcome`	`string`	Template name for the general SMS welcome message.
`smsTemplateOneTouchLogin`	`string`	Template name for one-touch login SMS.
`smsTemplateOneTouchLoginWelcome`	`string`	Template name for the welcome SMS after one-touch login.
`smsTemplateForgot`	`string`	Template name for forgot-password SMS OTP.
`smsTemplateUpdatePhone`	`string`	Template name for the SMS sent when updating a phone number.
`smsTemplateInstantOTPLogin`	`string`	Template name for instant OTP login via SMS.
`showPhoneFlag`	`boolean`	Renders country flag emojis in the phone input country code selector. When enabled, a flag emoji appears next to each country name in the dropdown and in the trigger. See Phone input below. Defaults to `false`.
`pinnedCountryCodes`	`string[]`	Array of dial codes (without `+`) pinned to the top of the phone input country dropdown, separated by a divider from the rest of the list. Only applies when `showPhoneFlag` is `true`. Defaults to `['1', '91']` (United States, Canada, and India).
`defaultPhonePrefix`	`string`	Default country dial code (without `+`) pre-selected when a phone input loads. Must match a dial code in the country list. Defaults to `'91'` (India). See Phone input below.
`showBackupCodes`	`boolean`	Enable to show Backup Code screens after MFA enrollment.
`storage`	`IStorage`	Pluggable storage backend for the SDK token cache. Defaults to an in-memory `Map` (tokens do not persist across page reloads). Pass an `IStorage` implementation to use `localStorage`, cookies, or any custom storage. The SDK exports `InMemoryStorage` as a built-in implementation.
`skipCheckSession`	`boolean`	When `true`, the SDK skips the `/ssologin/login` session check on initialization. Useful when you want to control session initialization manually. Defaults to `false`.

Option details

The fields below have nested shape, multiple modes, or interactions worth documenting in depth. Use this section as the deep reference when the one-line description in the table above is not enough.

successMessageConfig

Controls how success messages are displayed after form actions (e.g. registration, password reset).

Field	Type	Values	Default
`messageType`	`string`	`'toast'`, `'container'`, `'none'`	`'container'`
`duration`	`number`	Duration in milliseconds	`3200`

successMessageConfig: {
  messageType: 'container',
  duration: 5000
}

toast — displays a floating notification
container — renders the message inline within a designated container element
none — suppresses the message entirely (handle success via callbacks)

errorMessageConfig

Controls how error messages are displayed when form actions fail. Uses the same fields as successMessageConfig.

Field	Type	Values	Default
`messageType`	`string`	`'toast'`, `'container'`, `'none'`	`'toast'`
`duration`	`number`	Duration in milliseconds	`3200`

errorMessageConfig: {
  messageType: 'toast',
  duration: 4000
}

resendRestriction

Sets a cooldown timer (in seconds) on the resend button used by flows that send a one-time code or link. After the user clicks resend, the button is disabled and shows a countdown, reactivating only once the configured time has elapsed — throttling repeated send requests across all components. A flow that is not listed has no cooldown.

It is organized by delivery channel (email, sms) plus a workflow map for Identity Orchestration steps:

Key	Type	Description
`email`	`object`	Cooldown in seconds per email-based flow: `ForgotPassword`, `Registration`, `OneClickSignin`, `TwoFactorAuthentication`, `ForgotPIN`.
`sms`	`object`	Cooldown in seconds per SMS-based flow: `ForgotPassword`, `Registration`, `OneClickSignin`, `TwoFactorAuthentication`.
`workflow`	`object`	Cooldowns for workflows, keyed by workflow name, then by button ID (`smsotp`, `emailotp`, or a custom resend button's ID). Value is in seconds.

resendRestriction: {
  email: {
    ForgotPassword: 5,
    Registration: 10,
    OneClickSignin: 8,
    TwoFactorAuthentication: 3,
    ForgotPIN: 5,
  },
  sms: {
    ForgotPassword: 30,
    Registration: 45,
    OneClickSignin: 30,
    TwoFactorAuthentication: 15,
  },
  workflow: {
    loginWorkflow: {
      smsotp: 15,
      emailotp: 10,
      "<AdditionalButtonID>": 20,
    },
    signupWorkflow: {
      smsotp: 30,
    },
    "<WorkflowName>": {
      "<ButtonID>": 10,
    },
  },
}

For example, ForgotPassword: 5 disables the Forgot Password resend button for 5 seconds after each click. See Resend button cooldown for more.

formValidationMode

Controls when inline validation errors appear as users fill out SDK forms.

onBlur (default) — validation runs when the user leaves a field (on blur), including when they click outside the field or form. Error messages surface only after the user has finished interacting with each input.
onChange — validation runs as the user types, so invalid input shows an error message in real time.

formValidationMode: "onChange";

note

Submit-time validation always runs in both modes — required fields and format checks are still enforced when the form is submitted. formValidationMode only changes when inline errors appear before submission.

Phone input

The phone input country code selector supports flag emojis, pinned countries, and a configurable default prefix. These options affect every phone input field rendered by the SDK — including registration, login, profile editing, and passwordless flows.

Option	Type	Default	Description
`showPhoneFlag`	`boolean`	`false`	Renders a flag emoji next to each country name in the dropdown and in the trigger.
`pinnedCountryCodes`	`string[]`	`['1', '91']`	Dial codes (without `+`) pinned to the top of the dropdown, separated by a divider from the remaining countries.
`defaultPhonePrefix`	`string`	`'91'`	Dial code (without `+`) pre-selected when the phone input loads. Must match a dial code in the country list.

When showPhoneFlag is true, the SDK converts each country's ISO 3166-1 alpha-2 code into a flag emoji using Unicode regional indicator symbols — no images or external assets are required.

The pinnedCountryCodes array uses dial codes without the + prefix. For example, '1' covers both the United States and Canada (which share the +1 dial code), and '91' covers India. Pinned countries appear at the top of the dropdown above a divider line; the rest of the list follows alphabetically.

JavaScript SDK
React SDK
Auth Studio – Before Script

const LRObject = new LoginRadiusSDK({
  apiKey: "<YOUR_API_KEY>",
  showPhoneFlag: true,
  pinnedCountryCodes: ["1", "91", "44"],
  defaultPhonePrefix: "1",
});

<LoginRadiusProvider
  options={{
    apiKey: "<YOUR_API_KEY>",
    showPhoneFlag: true,
    pinnedCountryCodes: ["1", "91", "44"],
    defaultPhonePrefix: "1",
  }}
>
  <Auth />
</LoginRadiusProvider>

// Auth Studio → template editor → Pages → Auth → Before Script.
// Set the option on `commonoptions` before the SDK is created.
commonoptions.showPhoneFlag = true;
commonoptions.pinnedCountryCodes = ["1", "91", "44"];
commonoptions.defaultPhonePrefix = "1";

// Already present in the default Before Script:
var LRObject = new LoginRadiusSDK(commonoptions);

The example above pins the United States, Canada, India, and the United Kingdom to the top of the dropdown and defaults to the +1 prefix.

note

pinnedCountryCodes only takes effect when showPhoneFlag is true. When showPhoneFlag is false or omitted, the country selector renders without flags or pinned countries.

After a provider such as Google or Facebook authenticates a user, LoginRadius returns an access token to your application. The callbackInsideSameWindow and callbackType options work together to control how that token is returned and where the user lands afterward.

callbackInsideSameWindow (boolean, default false) determines where authentication takes place:

false — Authentication opens in a popup window. Your main page stays open and receives the token in the background once the user signs in.
true — The current tab navigates to the provider and then redirects back to your callbackUrl. No popup is used.

callbackType ('' | 'hash' | 'querystring', default '') determines the mechanism used to hand the token back to your application. Its exact effect depends on the value of callbackInsideSameWindow, as shown below.

Behavior reference

The matrix below shows the runtime result of every supported callbackInsideSameWindow + callbackType combination, so you can pick the pairing that matches your hosting model (static, SPA, or server-rendered) and security posture.

callbackInsideSameWindow	callbackType	Result
`true`	`''`	The token is sent to `callbackUrl` as an HTTP `POST`. Your server must handle this request; static and SPA hosts respond with `405`.
`true`	`'hash'`	The browser redirects to `callbackUrl#lr-token=<token>`. The SDK reads the token from the URL hash on load and signs the user in.
`true`	`'querystring'`	The browser redirects to `callbackUrl?lr-token=<token>`. The SDK reads the token from the query string on load and signs the user in. The page reloads in the process.
`false`	`''`	The token is passed to the main window in the background and the popup closes. The user is signed in without any change to the page URL.
`false`	`'hash'`	The token is appended to the main window's URL hash, and the SDK signs the user in as soon as the change is detected — no reload required. The popup then closes.
`false`	`'querystring'`	The token is appended to the main window's query string, which triggers a reload. The SDK detects the token during initialization on the new page and signs the user in.

How the token is detected

When the SDK initializes, it automatically checks for a pending social login token — no manual wiring is required. Depending on the configured callbackType, one of the following applies:

URL-based ('hash' or 'querystring') — The SDK inspects the URL hash first, then the query string. If a token is present, the user is signed in immediately.
Background message ('', popup flow) — The SDK listens for the token from the popup. For security, it accepts the message only from the LoginRadius domain or a configured customDomain, and validates the token before using it, so a token cannot be injected from another origin.

Examples

The snippets below show the three configurations you will reach for most often — the SPA default, a server-handled POST callback, and a same-tab redirect for static hosts.

// Standard popup (recommended for SPAs) — both values are the defaults
{
  callbackInsideSameWindow: false,
  callbackType: '',
}

// Same-window with hash (no server required)
{
  callbackInsideSameWindow: true,
  callbackType: 'hash',
  callbackUrl: 'https://yourapp.com/auth',
}

// Same-window with query string
{
  callbackInsideSameWindow: true,
  callbackType: 'querystring',
  callbackUrl: 'https://yourapp.com/auth',
}

// Popup with hash fallback
{
  callbackInsideSameWindow: false,
  callbackType: 'hash',
}

note

Using callbackType: 'querystring' triggers a full page reload. The SDK re-detects the token automatically on the new page, so no extra handling is needed, but any in-memory UI state is reset. Using callbackType: '' with callbackInsideSameWindow: true requires a server that can handle a POST request — on a static file server it returns 405 Method Not Allowed, so use 'hash' or 'querystring' during SPA development.

Validation rules

Validation rules define the constraints the SDK enforces on a form field before submission. You assign one or more rules to a field, and the SDK checks the field's value against each rule; when a rule fails, the SDK renders the matching message from mapValidationMessages (see Validation rule messages). Combine multiple rules on one field by separating them with a pipe (|), for example required|valid_email.

Rules that take a parameter use bracket notation — for example, min_length[8] requires at least eight characters, and matches[password] compares the field against another field named password. The formValidationMode option controls when these rules run relative to user input; see formValidationMode.

Rule	Parameter	Description
`required`	—	The field must not be empty.
`valid_email`	—	The value must be a well-formed email address.
`valid_username`	—	The value must be a valid username.
`valid_email_username`	—	The value must be a valid email address or a valid username.
`valid_phoneno`	—	The value must be a valid phone number.
`min_length[n]`	`n`	The value must be at least `n` characters long.
`max_length[n]`	`n`	The value must be no longer than `n` characters.
`exact_length[n]`	`n`	The value must be exactly `n` characters long.
`greater_than[n]`	`n`	The numeric value must be greater than `n`.
`less_than[n]`	`n`	The numeric value must be less than `n`.
`integer`	—	The value must be an integer.
`numeric`	—	The value must be numeric.
`decimal`	—	The value must be a decimal number.
`is_natural`	—	The value must be a natural number (`0`, `1`, `2`, and so on).
`is_natural_no_zero`	—	The value must be a natural number greater than zero.
`alpha`	—	The value must contain only alphabetic characters.
`alpha_numeric`	—	The value must contain only alphanumeric characters.
`alpha_dash`	—	The value must contain only alphanumeric characters, underscores, or dashes.
`alphanumeric_combo`	—	The value must contain a combination of letters and numbers.
`alpha_numeric_dash_combo`	—	The value must contain letters and numbers, and may include dashes.
`valid_url`	—	The value must be a well-formed URL.
`valid_ip`	—	The value must be a valid IP address.
`valid_base64`	—	The value must be a valid Base64-encoded string.
`valid_ca_zip`	—	The value must be a valid Canadian postal code.
`valid_credit_card`	—	The value must be a valid credit card number.
`callback_valid_date`	—	The value must be a valid date.
`matches[field]`	`field`	The value must match the value of the named field, such as a password confirmation.
`custom_validation`	—	Applies a custom validation function you supply for cases the built-in rules do not cover.

Usage examples

A representative end-to-end configuration combining the most common settings — credentials, theming, localization, CAPTCHA, templates, UI messaging, resend cooldowns, and validation mode:

const LRObject = new LoginRadiusSDK({
  // Core
  apiKey: "<YOUR_API_KEY>",
  verificationUrl: "https://yourdomain.com/verify",
  callbackUrl: "https://yourdomain.com/callback",
  callbackInsideSameWindow: false,
  callbackType: "hash",
  resetPasswordUrl: "https://yourdomain.com/reset-password",
  customDomain: "auth.yourdomain.com",
  apiCustomDomain: "api.yourdomain.com",
  projectionFields: ["Email", "FirstName", "LastName", "Uid"],
  isMobile: false,
  enableIdentifierCheck: true,

  // Theming
  templateName: "my-brand",
  styleName: "light-theme",

  // Localization
  disableLocalization: false,
  localizationConfig: {
    login: { buttonText: "Sign in" },
  },

  // CAPTCHA
  v2Recaptcha: true,
  captchaLanguage: "en",

  // Email templates
  verificationEmailTemplate: "verification-default",
  welcomeEmailTemplate: "welcome-v1",
  resetPasswordEmailTemplate: "reset-password-v1",
  resetPasswordConfirmationEmailTemplate: "reset-confirm-v1",
  passwordlessLoginEmailTemplate: "passwordless-email-v1",

  // SMS templates
  smsTemplate2FA: "otp-2fa",
  smsTemplatePhoneVerification: "phone-verify",
  passwordlessLoginSMSTemplate: "passwordless-sms-v1",

  // Phone input
  showPhoneFlag: true,
  pinnedCountryCodes: ["1", "91", "44"],
  defaultPhonePrefix: "1",

  // UI messaging
  successMessageConfig: { messageType: "toast", duration: 3200 },
  errorMessageConfig: { messageType: "container", duration: 5000 },

  // Resend button cooldown (seconds)
  resendRestriction: {
    email: { ForgotPassword: 5, Registration: 10 },
    sms: { ForgotPassword: 30 },
  },

  // Form validation
  formValidationMode: "onBlur",

  // Support
  contactusUrl: "https://yourdomain.com/support",
});

Action query parameter

The Auth component can read an action query parameter from the page URL to choose which screen it renders first. When action is present, it takes precedence over the Auth component's configured default screen.

For example, if Auth defaults to the login screen but the URL is ?action=register, the registration screen is shown instead.

info

The action query parameter is honored only when you initialize the Auth component. It is ignored when you initialize an individual component — such as Login, Register, or Forgot Password — directly.

Supported actions

The following values are recognized by the Auth component:

Action	Screen
`login`	Login screen (default)
`register`	Registration screen
`forgotpassword`	Forgot Password screen
`passwordless`	Passwordless Login screen
`logout`	Initiates the logout flow

Examples

Each URL below renders the corresponding screen when Auth is initialized on that page:

https://<tenant-name>.hub.loginradius.com/auth?action=register         → Registration screen
https://<tenant-name>.hub.loginradius.com/auth?action=forgotpassword   → Forgot Password screen
https://<tenant-name>.hub.loginradius.com/auth?action=passwordless     → Passwordless Login screen

Replace <tenant-name> with your LoginRadius Tenant name. The base URL (https://<tenant-name>.hub.loginradius.com/auth) defaults to the Login screen when no action is provided.

Requirements

Action query parameter support is available in both the JavaScript SDK and the React SDK, but only when the Auth component is initialized:

// Supported — the action parameter is processed
LRObject.init("auth", options); // JavaScript SDK
<Auth />; // React SDK

When an individual component is initialized directly, the SDK does not process the action query parameter, and any action specified in the URL is ignored.

Frontend SDKs overview

Compare the JavaScript and React SDKs and pick the right fit for your stack.

Set up your LoginRadius account

Retrieve the API Key and SOTT credentials the SDKs need to initialize.

Get started with the JavaScript SDK

Install, initialize, and render your first auth flow with the JavaScript SDK.

Get started with the React SDK

Wrap your app with the provider and render flows as JSX components.

Customization

Theming, messages, and resend cooldown.

Localization

Translate the SDK UI copy into any language.

Configuration

Reference

Option details

successMessageConfig

errorMessageConfig

resendRestriction

formValidationMode

Phone input

JavaScript SDK

React SDK

Auth Studio – Before Script

Social login callback options

Behavior reference

How the token is detected

Examples

Validation rules

Usage examples

Action query parameter

Supported actions

Examples

Requirements

Related resources