@auth0/auth0-acul-js - v1.0.0
    Preparing search index...

    Class LoginEmailVerification

    LoginEmailVerification classdesc Manages interactions for the "login-email-verification" screen. This screen prompts the user to enter a one-time code sent to their email address to verify their identity during the login process.

    It provides methods to submit the entered code (continueWithCode) or to request a new code if the original one was not received or has expired (resendCode).

    Inherits from BaseContext to access shared authentication flow data like transaction state, client information, and internationalization texts.

    // How to use the LoginEmailVerification screen SDK:
    import LoginEmailVerification from '@auth0/auth0-acul-js/login-email-verification';

    // Instantiate the manager for the login email verification screen
    const loginEmailVerificationManager = new LoginEmailVerification();

    // Accessing screen-specific texts (e.g., for titles, labels, button texts)
    const screenTexts = loginEmailVerificationManager.screen.texts;
    const pageTitle = screenTexts?.title || 'Verify Your Email';
    const codePlaceholder = screenTexts?.codePlaceholder || 'Enter code here';

    // Accessing transaction errors from a previous attempt
    const transactionErrors = loginEmailVerificationManager.transaction.errors;
    if (transactionErrors && transactionErrors.length > 0) {
      transactionErrors.forEach(error => {
        console.error(`Error Code: ${error.code}, Message: ${error.message}`);
        // Display these errors to the user appropriately.
      });
    }

    // Example of handling code submission from a form
    async function onCodeSubmit(enteredCode: string) {
      try {
        await loginEmailVerificationManager.continueWithCode({ code: enteredCode });
        // On successful verification, Auth0 will typically redirect the user.
        // If there's a validation error (e.g., invalid code), the page will
        // re-render, and `loginEmailVerificationManager.transaction.errors` will be updated.
      } catch (e) {
        // This catch block is for unexpected errors during submission (e.g., network issues).
        console.error('An unexpected error occurred while submitting the code:', e);
      }
    }

    // Example of handling a resend code request
    async function onResendCodeClick() {
      try {
        await loginEmailVerificationManager.resendCode();
        // Inform the user that a new code has been sent.
        // The page might re-render; check `loginEmailVerificationManager.transaction.errors`
        // for issues like "too-many-emails".
      } catch (e) {
        console.error('An unexpected error occurred while resending the code:', e);
      }
    }

    Hierarchy

    • BaseContext
      • LoginEmailVerification

    Implements

    Index

    Constructors

    constructor

    Properties

    branding client organization prompt screen tenant transaction untrustedData user screenIdentifier

    Methods - Language

    changeLanguage

    Methods - Other

    continueWithCode getErrors resendCode resendManager

    Constructors

    Properties

    branding: Screens.BrandingMembers
    client: Screens.ClientMembers
    organization: Screens.OrganizationMembers
    prompt: Screens.PromptMembers
    screen: Screens.ScreenMembers
    tenant: Screens.TenantMembers
    transaction: Screens.TransactionMembers
    untrustedData: Screens.UntrustedDataMembers
    user: Screens.UserMembers
    screenIdentifier: string = ScreenIds.LOGIN_EMAIL_VERIFICATION

    The unique identifier for the Login Email Verification screen. This static property is used by the SDK's BaseContext to ensure that the class is instantiated in the correct screen context.

    Methods - Language

    • Utility Feature

      Changes the language/locale for the current authentication flow.

      This method triggers a language change by submitting the new locale preference to the server with the 'change-language' action. The language change will cause the current screen to re-render with the new locale.

      Parameters

      • options: Screens.LanguageChangeOptions

        Language change options including the target language code

        Options for changing the language/locale during the authentication flow

        • [key: string]: string | number | boolean | undefined

          Additional custom fields to be submitted along with the language change. Custom fields should be prefixed with 'ulp-'.

        • language: string

          Short language name (locale code) to be set (e.g., 'en', 'fr', 'es').

        • Optionalpersist?: "session"

          Defines persistence scope for the language preference. Currently only 'session' is supported.

          'session'

      Returns Promise<void>

      A promise that resolves when the form submission is complete

      import LoginId from "@auth0/auth0-acul-js/login-id";

      const loginManager = new LoginId();

      // Change language to French
      await loginManager.changeLanguage({
        language: 'fr',
        persist: 'session'
      });

      import LoginPassword from "@auth0/auth0-acul-js/login-password";

      const loginPasswordManager = new LoginPassword();

      // Change language to Spanish with additional custom data
      await loginPasswordManager.changeLanguage({
        language: 'es',
        persist: 'session',
        'ulp-custom-field': 'custom-value'
      });
      • This method is available on all screen instances that extend BaseContext
      • The language must be one of the enabled locales configured in your Auth0 tenant
      • The screen will automatically re-render with the new language after submission
      • Custom fields can be included and will be accessible in the Post Login Trigger

    Methods - Other

    • Submits the email verification code entered by the user to Auth0. This method prepares and posts the form data, including the verification code and the required action: "default", to the /u/login-email-verification endpoint.

      Parameters

      Returns Promise<void>

      A promise that resolves once the form submission is initiated. Typically, a successful submission leads to a server-side redirect. If the code is incorrect or an error occurs, the page will re-render, and this.transaction.errors will be populated.

      If the payload.code is missing or not a string. It can also throw if FormHandler encounters an issue during submission (e.g. network error). Auth0 validation errors (e.g. "invalid-code") are not thrown as JS errors but are made available in this.transaction.errors post-operation.

      const manager = new LoginEmailVerification();
      // Assuming 'userInputCode' is a string obtained from a form input
      manager.continueWithCode({ code: userInputCode })
        .catch(err => {
          // Handle unexpected submission errors
          displayGlobalError("Could not submit your code. Please try again.");
        });
      // After the operation, check manager.transaction.errors for validation messages.

    • Requests Auth0 to send a new verification code to the user's email address. This is typically used when the user didn't receive the original code, or it has expired. This method posts form data with action: "resend-code" to the /u/login-email-verification endpoint.

      Parameters

      Returns Promise<void>

      A promise that resolves once the resend request is initiated. A successful request usually means a new email is dispatched. The page might re-render, and this.transaction.errors could be updated if, for example, rate limits (too-many-emails) are hit.

      If FormHandler encounters an issue (e.g. network error). Server-side validation errors (e.g. rate limits) are not thrown as JS errors but are made available in this.transaction.errors.

      const manager = new LoginEmailVerification();
      manager.resendCode()
        .then(() => {
          // Inform the user that a new code has been sent.
          showNotification("A new verification code is on its way!");
        })
        .catch(err => {
          // Handle unexpected submission errors
          displayGlobalError("Could not request a new code. Please try again later.");
        });
      // After the operation, check manager.transaction.errors for specific issues.
    • Utility Feature

      Gets resend functionality with timeout management for this screen

      Parameters

      Returns Screens.ResendControl

      ResendControl object with startResend method

      import LoginEmailVerification from '@auth0/auth0-acul-js/login-email-verification';

      const loginEmailVerification = new LoginEmailVerification();
      const { startResend } = loginEmailVerification.resendManager({
        timeoutSeconds: 15,
        onStatusChange: (remainingSeconds, isDisabled) => {
          console.log(`Resend available in ${remainingSeconds}s, disabled: ${isDisabled}`);
        },
        onTimeout: () => {
          console.log('Resend is now available');
        }
      });

      // Call startResend when user clicks resend button
      startResend();

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods - Language
    Methods - Other