Lock API Reference

Lock has many methods, features, and configurable options. This reference is designed to direct you to the ones that you need, and discuss how to use them. Click below to go straight the method you're looking for, or just browse! If you're looking for information about events emitted by Lock, they're listed under the on() method section!

• new Auth0Lock - Instantiating Lock

• getUserInfo() - Obtaining the profile of a logged in user

• show() - Showing the Lock widget

• on() - Listening for events

• resumeAuth() - Use to complete authentication flow when autoParseHash is false

• checkSession() - Get a new token from Auth0 for an authenticated user

• logout() - Log out the user

new Auth0Lock(clientID, domain, options)

Initializes a new instance of Auth0Lock configured with your application's clientID and your account's domain from your Auth0 management dashboard. The third and optional parameter is an options object used to configure Lock for your application's needs. You can find this information at your application settings.

• clientId {String}: Required parameter. Your application's clientId in Auth0.

• domain {String}: Required parameter. Your Auth0 domain. Usually your-account.auth0.com.

• options {Object}: Optional parameter. Allows for the configuration of Lock's appearance and behavior. See the configuration options page for details.

var Auth = (function() {

  var privateStore = {};

  function Auth() {
    // Instantiate Lock - without custom options
    this.lock = new Auth0Lock(
      '<{yourClientId}>',
      '<{yourDomain}>'
    );
  }

  Auth.prototype.getProfile = function() {
    return privateStore.profile;
  };

  Auth.prototype.authn = function() {
    // Listening for the authenticated event and get profile
    this.lock.on("authenticated", function(authResult) {
      // Use the token in authResult to getUserInfo() and save it if necessary
      this.getUserInfo(authResult.accessToken, function(error, profile) {
        if (error) {
          // Handle error
          return;
        }

        //save Access Token only if necessary
        privateStore.accessToken = accessToken;
        privateStore.profile = profile;

        // Update DOM
      });
    });
  };
  return Auth;
}());

getUserInfo(accessToken, callback)

Once the user has logged in and you are in possession of a token, you can use that token to obtain the user's profile with getUserInfo. This method replaces the deprecated getProfile().

• accessToken {String}: User token.

• callback {Function}: Will be invoked after the user profile been retrieved.

lock.getUserInfo(accessToken, function(error, profile) {
  if (!error) {
    alert("hello " + profile.name);
  }
});

show(options)

The show method displays the widget. Beginning with Lock version 10.2.0, the show method can now accept an options object as a parameter. Note that this parameter is meant to be used as a way to override your Lock's options for this particular displaying of the widget - options should be set when instantiating Lock, and overridden, only if needed for your specific use case, here.

The following subset of options to be overridden from the values they were given (or their defaults) when Lock was instantiated:

• allowedConnections

• auth.params

• allowLogin

• allowSignUp

• allowForgotPassword

• initialScreen

• rememberLastLogin

For more detail on the entire list of configurable options that can be chosen when instantiating Lock, as opposed to the limited subset above that can be overridden in the show method, please see the user configurable options page.

Options override examples:

// Show the Lock widget, without overriding any options
lock.show();

// Show the Lock widget, overriding some options
lock.show({
  allowedConnections: ["twitter", "facebook"],
  allowSignUp: false
});

Options should be set when first instantiating Lock var lock = new Auth0Lock(clientId, domain, options);. Options should only be passed to show in order to override your previously set options while displaying the widget at this particular time and place.

There is an additional option that can be set in the show method called flashMessage.

This object is only available as an option for the show method, not for use in the normal options object when instantiating Lock. The flashMessage object shows an error or success flash message when Lock is shown. It has the following parameters:

• type {String}: The message type, it should be either error or success.

• text {String}: The text to show.

lock.show({
  flashMessage:{
    type: 'success',
    text: 'Amazing Success!!'
  }
});

A practical application of the flashMessage option is to handle authorization errors. The flashMessage can be populated with error description text.

lock.on('authorization_error', function(error) {
  lock.show({
    flashMessage: {
      type: 'error',
      text: error.errorDescription
    }
  });
});

So, if tester@example.com were now to try to sign in, being a user who is blocked, the user will be shown Lock again, with a top bar displaying the error message, rather than simply failing to login and Lock closing.

hide()

The hide method closes the widget if it is currently open. The widget closes itself under most circumstances, so this method would primarily be invoked in specific use cases only. For instance, one might wish to listen for the unrecoverable_error event and then hide the Lock and redirect to their own custom error page. Another example is users who are implementing popup mode, and might need to manually hide the widget after the authenticated event fires.

Example usage to hide (close) the Lock widget in popup mode:

// Listen for authenticated event and hide Lock
lock.on("authenticated", function() {
  lock.hide();

  // Whatever else you'd like to do on authenticated event

});

Lock will emit events during its lifecycle. The on method can be used to listen for particular events and react to them.

• show: emitted when Lock is shown. Has no arguments.

• hide: emitted when Lock is hidden. Has no arguments.

• unrecoverable_error: emitted when there is an unrecoverable error, for instance when no connection is available. Has the error as the only argument.

• authenticated: emitted after a successful authentication. Has the authentication result as the only argument. The authentication result contains the token which can be used to get the user's profile or stored to log them in on subsequent checks.

• authorization_error: emitted when authorization fails. Has error as the only argument.

• hash_parsed: every time a new Auth0Lock object is initialized in redirect mode (the default), it will attempt to parse the hash part of the url looking for the result of a login attempt. This is a low level event for advanced use cases and authenticated and authorization_error should be preferred when possible. After that this event will be emitted with null if it couldn't find anything in the hash. It will be emitted with the same argument as the authenticated event after a successful login or with the same argument as authorization_error if something went wrong. This event won't be emitted in popup mode because there is no need to parse the url's hash part.

• forgot_password ready: emitted when the "Forgot password" screen is shown. (Only in Version >10.18)

• forgot_password submit: emitted when the user clicks on the submit button of the "Forgot password" screen. (Only in Version >10.14)

• signin ready: emitted when the "Sign in" screen is shown.

• signup ready: emitted when the "Sign up" screen is shown.

• signin submit: emitted when the user clicks on the submit button of the "Login" screen. (Only in Version >10.18)

• signup submit: emitted when the user clicks on the submit button of the "Sign Up" screen. (Only in Version >10.18)

• federated login: emitted when the user clicks on a social connection button. Has the connection name and the strategy as arguments. (Only in Version >10.18)

• socialOrPhoneNumber ready: emitted when the Passwordless screen with Social + Phone Number is shown

• socialOrPhoneNumber submit: emitted when the Passwordless screen with Social + Phone Number is submitted

• socialOrEmail ready: emitted when the Passwordless screen with Social + Email is shown

• socialOrEmail submit: emitted when the Passwordless screen with Social + Email is submitted

• vcode ready: emitted when the Passwordless screen with the one-time-password is shown

• vcode submit: emitted when the Passwordless screen with the one-time-password is submitted

The authenticated event listener has a single argument, an authResult object. This object contains the following properties: accessToken, idToken, state, refreshToken and idTokenPayload.

An example use of the authenticated event:

var Auth = (function() {

  var privateStore = {};

  function Auth() {
    this.lock = new Auth0Lock(
      '<{yourClientId}>',
      '<{yourDomain}>'
    );
  }

  Auth.prototype.getProfile = function() {
    return privateStore.profile;
  };

  Auth.prototype.authn = function() {
    // Listening for the authenticated event
    this.lock.on("authenticated", function(authResult) {
      // Use the token in authResult to getUserInfo() and save it if necessary
      this.getUserInfo(authResult.accessToken, function(error, profile) {
        if (error) {
          // Handle error
          return;
        }

        privateStore.profile = profile;

      });
    });
  };
  return Auth;
}());

This method can only be used when you set the auth.autoParseHash option to false. You'll need to call resumeAuth to complete the authentication flow. This method is useful when you're using a client-side router that uses a # to handle urls (angular2 with useHash, or react-router with hashHistory).

• hash {String}: The hash fragment received from the redirect.

• callback {Function}: Will be invoked after the parse is done. Has an error (if any) as the first argument and the authentication result as the second one. If there is no hash available, both arguments will be null.

lock.resumeAuth(hash, function(error, authResult) {
  if (error) {
    alert("Could not parse hash");
  }
  //This is just an example; you should not log Access Tokens in production.
  console.log(authResult.accessToken);
});

The checkSession method allows you to acquire a new token from Auth0 for a user who is already authenticated against Auth0 for your domain. It takes the following parameters:

• options {Object}: Optional. Accepts any valid OAuth2 parameters that would normally be sent to /authorize. If you omit them, it will use the ones provided when initializing Auth0.

• callback {Function}: Will be invoked with the token renewal result. Has an error (if any) as the first argument and the authentication result as the second one.

lock.checkSession({}, function(err, authResult) {
  // handle error or new tokens
});

Logs out the user.

• options {Object}: This is optional and follows the same rules as auth0.js logout().

lock.logout({
  returnTo: 'https://myapp.com/bye-bye'
});