Add Bot Detection to Custom Login Pages

If you build a custom login page using auth0.js, you can enable bot detection to render a CAPTCHA step in scenarios when a login request is determined by Auth0 to be high risk. Your custom login form code must handle scenarios where the user is asked to pass a CAPTCHA step. If you don't account for this scenario, your application may cause an error.

Bot detection is only supported for custom login pages hosted by Auth0. You may need to contact your account representative to enable this feature for your tenant.

Use custom login page template

Auth0 provides a template for you to use with code to handle high-risk logins.

  1. Go to Dashboard > Branding > Universal Login and select Classic.

  2. Click the Login tab and enable the Customize Login Page switch if it is not already enabled.

  3. Locate the Default Templates drop-down menu and select Custom Login Form.

    Dashboard Branding Universal Login Classic Login Tab Custom Login Form

  4. Copy the template to use for your custom login page. Use the steps below to customize the form.

  5. Customize the login form (see below), and replace you new form in the Login tab.

  6. Click Preview to see your new form.

  7. Click Save Changes.

Customize login form

Your code must use auth0.js version 9.16 or higher.

<script src=""></script>

  1. Add an element to render the CAPTCHA below your password input and above your sign-up and login buttons. For example: <div class="captcha-container"></div>

  2. Initialize the CAPTCHA component after the WebAuth constructor.

    var webAuth = new auth0.WebAuth(params);
    var captcha = webAuth.renderCaptcha(

  3. Append the value of the CAPTCHA with captcha: captcha.getValue() to the login and signup calls as follows:

      realm: connection,
      username: username,
      password: password,
      captcha: captcha.getValue()
    }, function(err) {
      connection: databaseConnection,
      email: email,
      password: password,
      captcha: captcha.getValue()
    }, function(err) {

    To learn more about the login cb parameter, read auth0.js login documentation.

  4. Reload the CAPTCHA in your generic error handling logic.

    function displayError(err) {
      var errorMessage = document.getElementById('error-message');
      errorMessage.innerHTML = err.description; = 'block';

The render method supports an optional parameter that allows you to change the default templates. You can find the default values here:

Learn more