authrocket.js (client-side JS)

authrocket.js enables you to host login and signup forms on your own site, but have AuthRocket do all the backend processing via AJAX.

Both logins and signups are supported and may be used independently.

authrocket.js is just one method of handling logins and signups using AuthRocket. See Logins, Signups, and Configuring LoginRocket for more.

authrocket.js uses the LoginRocket API. Below is an overview of how to get up and running with authrocket.js. See the LoginRocket API docs for more details and for how to handle logins from any untrusted client, whether a web browser, iOS app, Android app, or Windows or Mac client.

Logins

1. Add authrocket.js to your page

authrocket.js relies on jQuery being present (and included before authrocket.js). If you aren’t already using it, add it now:

<script src="https://code.jquery.com/jquery-1.11.2.min.js" type="text/javascript"></script>

Then, add authrocket.js to your page:

<script src="https://js.authrocket.com/v1/authrocket.js" type="text/javascript"></script>

2. Configure your LoginRocket URL

Initialize authrocket.js with the authrocket.js URL from the Integration page (select the proper Connected App first, if you have more than one). This is not the same as the API’s URL. Read more about getting a LoginRocket URL.

AuthRocket.setInstanceUrl('YOUR_LOGINROCKET_URL');

For example:

AuthRocket.setInstanceUrl('https://myapp.e1.loginrocket.com/');

3. Setup a callback for the login form

Build a callback to tie together your login form and authrocket.js:

$('#login-form').submit(function(event){
  AuthRocket.authenticate({
    username: $("#login_username").val(),
    password: $("#login_password").val()
  }, arLoginHandler);
  return false;
});

arLoginHandler at the end is a response handler (see next step). It may be left out if you choose to use the default response handler.

4. Define a response handler

Optionally define a response handler to render errors or complete the login.

If left out, errors will be shown with alert() and the user will be redirected to response.url on success. To use the default handler, leave out arLoginHandler in the previous step.

The response object contains the following:
error - A single string of all error messages combined. Useful for quick display.
errors - An array of error messages. Useful for more precise formatting of errors.
token - On success, a login token.
url - The login handler URL with the token already appended.

function arLoginHandler(response){
  if (response.error) {
    $("#login-errors").text(response.error);
  } else {
    window.location = response.url;
    // alternate way of using the response:
    // var form = $('#login-form');
    // var token = response.token;
    // form.append($('<input type="hidden" name="login[token]" >').val(token));
    // form.get(0).submit();
  }
}

5. Putting it all together

Here’s what it looks like put together:

<head>
  ...
  <script src="https://js.authrocket.com/v1/authrocket.js" type="text/javascript"></script>
  <script type="text/javascript">
    AuthRocket.setInstanceUrl('YOUR_LOGINROCKET_URL');
    $(function(){
      $('#login-form').submit(function(event){
        AuthRocket.authenticate({
          username: $('#login_username').val(),
          password: $('#login_password').val()
        }, arLoginHandler);
        return false;
      });
      function arLoginHandler(response){
        if (response.error) {
          $("#login-errors").text(response.error);
        } else {
          window.location = response.url;
        }
      };
    });
  </script>
</head>

6. Using the login token

A login token is sent to your app with the key token. This token is JWT-compatible and should be validated. See Verifying Logins in our Integration Guide (or Ruby version).

Signups

1. Add authrocket.js to your page

authrocket.js relies on jQuery being present (and included before authrocket.js). If you aren’t already using it, add it now:

<script src="https://code.jquery.com/jquery-1.11.2.min.js" type="text/javascript"></script>

Then, add authrocket.js to your page:

<script src="https://js.authrocket.com/v1/authrocket.js" type="text/javascript"></script>

2. Configure your LoginRocket URL

Initialize authrocket.js with the authrocket.js URL from the Integration page (select the proper Connected App first, if you have more than one). This is not the same as the API’s URL. Read more about getting a LoginRocket URL.

AuthRocket.setInstanceUrl('YOUR_LOGINROCKET_URL');

For example:

AuthRocket.setInstanceUrl('https://mysubdomain.e1.loginrocket.com/');

3. Setup a callback for the signup form

Build a callback to tie together your signup form and authrocket.js:

$('#signup-form').submit(function(event){
  AuthRocket.signup({
    email: $("#signup_email").val(),
    password: $("#signup_password").val(),
    password_confirmation: $("#signup_password_confirmation").val()
  }, arSignupHandler);
  return false;
});

See the LoginRocket API for available attributes.

arSignupHandler at the end is a response handler (see next step). It may be left out if you choose to use the default response handler.

4. Define a response handler

Optionally define a response handler to render errors or complete the signup.

If left out, errors will be shown with alert() and the user will be redirected on success. To use the default handler, leave out arSignupHandler in the previous step.

A. If LoginRocket’s signup mode is user:

The response object contains the following:
error - A single string of all error messages combined. Useful for quick display.
errors - An array of error messages. Useful for more precise formatting of errors.
token - On success, a login token.
url - The login handler URL with both the token and signup=true appended.

function arSignupHandler(response){
  if (response.error) {
    $("#signup-errors").text(response.error);
  } else {
    window.location = response.url;
  }
}

B. If LoginRocket’s signup mode is user_token (Signup Token mode):

The response object contains the following:
error - A single string of all error messages combined. Useful for quick display.
errors - An array of error messages. Useful for more precise formatting of errors.
token - On success, a signup token.
url - The signup token handler URL with the token already appended.

function arSignupHandler(response){
  if (response.error) {
    $("#signup-errors").text(response.error);
  } else {
    var form = $('#signup-form');
    var token = response.token;
    form.append($('<input type="hidden" name="signup[user_token_id]" >').val(token));
    form.get(0).submit();
    // alternate ways of using the response:
    // $("#signup_token").val(response.token);
    // window.location = response.url;
  }
}

5. Putting it all together

Here’s what it looks like put together:

<head>
  ...
  <script src="https://js.authrocket.com/v1/authrocket.js" type="text/javascript"></script>
  <script type="text/javascript">
    AuthRocket.setInstanceUrl('YOUR_LOGINROCKET_URL');
    $(function(){
      $('#signup-form').submit(function(event){
        AuthRocket.signup({
          email: $("#signup_username").val(),
          password: $("#signup_password").val(),
          password_confirmation: $("#signup_password_confirmation").val()
        }, arSignupHandler);
        return false;
      });
      function arSignupHandler(response){
        if (response.error) {
          $("#signup-errors").text(response.error);
        } else {
          window.location = response.url;
        }
      };
    });
  </script>
</head>

6. Using the signup token

If Signups are configured to create Users, a login token (not a signup token) is created and will be handled identically to 6. Using the login token above. If Signups are instead configured to create Signup Tokens, then continue here.

If AuthRocket.signup() is successful, it returns a Signup Token which is then sent to your app with the key token.

Assuming the rest of your signup process passes any other validations, this token should be submitted by your app to AuthRocket using the Create a User API call.

If there is some other signup related error (for example, a payment attempt fails), simply don’t submit the Signup Token. The same user can create multiple Signup Tokens without causing any issues.

FAQs

What other functions does authrocket.js support?

There are quite a number of other functions, including password resets and changes, email verification, etc. See the LoginRocket API for full details.

What if I don’t use jQuery?

If you don’t use any similar libraries, one option is to use it just on the page(s) where you display your login and/or signup form. Another option is to create your own functions for whatever library you use. The LoginRocket API supports both CORS and JSONP and is very easy to use with any library that has built-in AJAX or JSONP support.

What about CORS?

The LoginRocket API supports both CORS and JSONP. At this time, authrocket.js uses JSONP for maximum compatibility.

All major, modern browsers support CORS. If you need to support really old browsers, use JSONP. There are also isolated reports of old proxies, firewalls, and VPN clients having trouble with the OPTIONS requests that CORS sometimes makes.

IE 8-9 have a half-baked version of CORS. You will probably need to use GET requests (same as JSONP would).

Questions? Find a Typo? Get in touch.