LoginRocket API

The LoginRocket API enables logins and signups from untrusted clients, such as web browsers or iOS and Android apps.

This API is accessed via *.loginrocket.com URLs. See Accessing the LoginRocket API for more details.

It is the same API used by authrocket.js, so if your client app runs in a web browser, you may want to use authrocket.js instead (but you’re free to write your own code against the API if you prefer).

Requests shown below as POST can also be sent as GET. GET requests are intended for use with JSONP.

Both CORS and JSONP are supported.

Fields

FieldValueReq/DefaultNotes
token string Login (JWT) token, 2FA login token, Signup token, Password reset token, or Email verification token.
url url Auto-generated Login or Signup Token Handler URL with token already appended.

Logins & Signups:

username string Required for Realms using standard (non-email) usernames.
email string Required for Realms using email usernames.
password string Required
code string 2FA code, when completing a 2FA login.
callback string Optional Send with JSONP requests only.

Signups only:

password_confirmation string

Always allowed and must match password if present. Required if LoginRocket configured as such.

email_confirmation string

Must match email if present.

first_name string Always allowed. Required if LoginRocket configured as such.
last_name string Always allowed. Required if LoginRocket configured as such.
org_name string

Used only if signup_mode is user_org. Required if LoginRocket configured as such.

username and email

If your Realm is set to validate usernames as emails (instead of validating as standard), then username should be left out; email will automatically be used.

Confirmations

Both password_confirmation and email_confirmation are optional. If present, confirmation will be checked. If missing, the check will be bypassed.

Login

Authenticates a user using a password.

Request

Example
POST /v1/login
{ "username" : "frank",
  "password" : "secret"
}
curl -X POST https://sample.loginrocket.e1.com/v1/login \
  -d username=frank -d password=secret
$('#form').submit(function(event){
  AuthRocket.authenticate({
    username: $("#field-username").val(),
    password: $("#field-password").val()
  }, arLoginHandler);
  return false;
});

function arLoginHandler(response){
  if (response.error) {
    $("#messages").text(response.error);
  } else if (response.result == 'need_mfa') {
    // show user the 2FA verification form and use Verify a 2FA login to complete the login
    // 2FA token is in response.token (starts with kli_)
  } else {
    window.location = response.url;
  }
}

Response

Example

On success, Status: 200 with:

{ "result" : "okay",
  "token" : "4JagCZeSCVH...ae2kd9ZOaWo",
  "url" : "https://yourapp.com/login?token=4JagCZeSCVH...ae2kd9ZOaWo"
}

On success, if requires 2FA to finish login, Status: 200 with:

{ "result" : "need_mfa",
  "token" : "kli_3zpHFOD3iXYp8gY8ZImPTh"
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, Status: 200 with:

{ "result" : "okay",
  "token" : "4JagCZeSCVH...ae2kd9ZOaWo",
  "url" : "https://yourapp.com/login?token=4JagCZeSCVH...ae2kd9ZOaWo"
}

On success, if requires 2FA to finish login, Status: 200 with:

{ "result" : "need_mfa",
  "token" : "kli_3zpHFOD3iXYp8gY8ZImPTh"
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, calls arLoginHandler with response object:

{ "result" : "okay",
  "token" : "4JagCZeSCVH...ae2kd9ZOaWo",
  "url" : "https://yourapp.com/login?token=4JagCZeSCVH...ae2kd9ZOaWo"
}

On success, if requires 2FA to finish login, calls arLoginHandler with response object:

{ "result" : "need_mfa",
  "token" : "kli_3zpHFOD3iXYp8gY8ZImPTh"
}

On failure, calls arLoginHandler with response object:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

Verify a 2FA login

Verifies a 2FA code and completes a password authentication.

Request

Example
POST /v1/verify_login
{ "username" : "frank",
  "token" : "kli_3zpHFOD3iXYp8gY8ZImPTh",
  "code" : "123456"
}
curl -X POST https://sample.loginrocket.e1.com/v1/login \
  -d username=frank -d token=kli_3zpHFOD3iXYp8gY8ZImPTh -d code=123456
$('#form').submit(function(event){
  AuthRocket.authenticateCode({
    username: $("#hidden-field-username").val(),
    token: $("#hidden-field-token").val(),
    code: $("#field-code").val()
  }, arLoginHandler2);
  return false;
});

function arLoginHandler2(response){
  if (response.error) {
    $("#messages").text(response.error);
  } else {
    window.location = response.url;
  }
}

Response

Example

On success, Status: 200 with:

{ "token" : "4JagCZeSCVH...ae2kd9ZOaWo",
  "url" : "https://yourapp.com/login?token=4JagCZeSCVH...ae2kd9ZOaWo"
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, Status: 200 with:

{ "token" : "4JagCZeSCVH...ae2kd9ZOaWo",
  "url" : "https://yourapp.com/login?token=4JagCZeSCVH...ae2kd9ZOaWo"
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, calls arLoginHandler2 with response object:

{ "token" : "4JagCZeSCVH...ae2kd9ZOaWo",
  "url" : "https://yourapp.com/login?token=4JagCZeSCVH...ae2kd9ZOaWo"
}

On failure, calls arLoginHandler2 with response object:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

Logout

Ends a login session.

By default, deletes the last known session (stored using a LoginRocket cookie).

Browsers configured to block 3rd-party cookies will not send the cookie and the session will not be properly logged out. It is recommended to use the token parameter if possible.

Specify token parameter to ensure a particular session is ended instead.

Parameters

ParamValueDefault
token string Login/session token. Optional, but recommended.

Request

Example
POST /v1/logout
{ "token" : "abc...xyz"
}
curl -X POST https://sample.loginrocket.e1.com/v1/logout \
  -d token=abc...xyz
$('#logout-button').click(function(event){
  AuthRocket.logout({token: "abc...xyz"}, arLogoutHandler);
  return false;
});

function arLogoutHandler(response){
  if (response.error) {
    alert(response.error);
  } else {
    window.location = '/';
  }
}

Response

Example

On success, Status: 200.

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, Status: 200.

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, calls arLogoutHandler with an empty response object:

{}

On failure, calls arLogoutHandler with response object:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

Check session token

Checks the validity of a login (session) token, which must be a full JWT.

Requires that the realm is using managed sessions.

Request

Example
POST /v1/check_session
{ "token" : "a-long-session-token"
}
curl -X POST https://sample.loginrocket.e1.com/v1/check_session \
  -d token=a-long-session-token
$('#some-element').click(function(event){
  AuthRocket.checkSession({
    token: $("#hidden-session-token").val()
  }, arSessionHandler);
  return false;
});

function arSessionHandler(response){
  if (response.valid) {
    console.log('Session is valid');
  } else {
    console.log('Session is not valid');
    // trigger request for login
  }
}

Response

Example

On success, Status: 200 with:

{ "valid" : true
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ],
  "valid" : false
}

On success, Status: 200 with:

{ "valid" : true
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ],
  "valid" : false
}

On success, calls arSessionHandler with response object:

{ "valid" : true
}

On failure, calls arSessionHandler with response object:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ],
  "valid" : false
}

Forgot password

Requests a password reset token.

Request

Example
POST /v1/forgot_password
{ "username" : "frank"
}
curl -X POST https://sample.loginrocket.e1.com/v1/forgot_password \
  -d username=frank
$('#form').submit(function(event){
  AuthRocket.forgotPassword({
    username: $("#field-username").val()
  }, arForgotHandler);
  return false;
});

function arForgotHandler(response){
  if (response.error) {
    $("#messages").text(response.error);
  } else {
    $("#messages").text(response.message);
  }
}

Response

Example

On success, Status: 200 with:

{ "message" : "You should receive a password reset token within a few minutes. If not, check your spam folder."
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, Status: 200 with:

{ "message" : "You should receive a password reset token within a few minutes. If not, check your spam folder."
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, calls arForgotHandler with response object:

{ "message" : "You should receive a password reset token within a few minutes. If not, check your spam folder."
}

On failure, calls arForgotHandler with response object:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

Reset password

Resets a password using a reset token.

Request

Example
POST /v1/reset_password
{ "username" : "frank",
  "token" : "kpw_sxBqZsIN1HWHONSqwvyj64",
  "password" : "secret",
  "password_confirmation" : "secret"
}
curl -X POST https://sample.loginrocket.e1.com/v1/reset_password \
  -d username=frank -d token=kpw_sxBqZsIN1HWHONSqwvyj64 \
  -d password=secret -d password_confirmation=secret
$('#form').submit(function(event){
  AuthRocket.resetPassword({
    username: $("#field-username").val(),
    token: $("#field-token").val(),
    password: $("#field-password").val(),
    password_confirmation: $("#field-password-confirmation").val()
  }, arResetHandler);
  return false;
});

function arResetHandler(response){
  if (response.error) {
    $("#messages").text(response.error);
  } else {
    $("#messages").text(response.message);
  }
}

Response

Example

On success, Status: 200 with:

{ "message" : "Your password has been reset."
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, Status: 200 with:

{ "message" : "Your password has been reset."
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, calls arResetHandler with response object:

{ "message" : "Your password has been reset."
}

On failure, calls arResetHandler with response object:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

Update password

Allows a user to update (change) their password.

Requires a valid login (session) token, which must be a full JWT.

Request

Example
POST /v1/update_password
{ "token" : "a-long-session-token",
  "current_password" : "old_secret",
  "password" : "new_secret",
  "password_confirmation" : "new_secret"
}
curl -X POST https://sample.loginrocket.e1.com/v1/update_password \
  -d token=a-long-session-token -d current_password=old_secret \
  -d password=new_secret -d password_confirmation=new_secret
$('#form').submit(function(event){
  AuthRocket.updatePassword({
    token: $("#hidden-session-token").val(),
    current_password: $("#field-current-password").val(),
    password: $("#field-password").val(),
    password_confirmation: $("#field-password-confirmation").val()
  }, arUpdateHandler);
  return false;
});

function arUpdateHandler(response){
  if (response.error) {
    $("#messages").text(response.error);
  } else {
    $("#messages").text(response.message);
  }
}

Response

Example

On success, Status: 200 with:

{ "message" : "Your password has been updated."
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, Status: 200 with:

{ "message" : "Your password has been updated."
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, calls arUpdateHandler with response object:

{ "message" : "Your password has been updated."
}

On failure, calls arUpdateHandler with response object:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

Signup

Creates a new user or user token.

Request

Example
POST /v1/signup
{ "email" : "frank@example.com",
  "password" : "secret",
  "password_confirmation" : "secret"
}
curl -X POST https://sample.loginrocket.e1.com/v1/signup \
  -d email=frank@example.com -d password=secret \
  -d password_confirmation=secret
$('#form').submit(function(event){
  AuthRocket.signup({
    email: $("#field-email").val(),
    password: $("#field-password").val(),
    password_confirmation: $("#field-password-confirmation").val()
  }, arSignupHandler);
  return false;
});

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

// alternate handler when signup mode is 'user_token' (Signup Token mode)
function arSignupHandler(response){
  if (response.error) {
    $("#messages").text(response.error);
  } else {
    var form = $('#form');
    form.append($('<input type="hidden" name="signup[user_token_id]" >').val(response.token));
    form.get(0).submit();
  }
}

Response

Example

When LoginRocket’s signup mode is user, returns same response as Login with &signup=true added to url.

When signup mode is user_token (Signup Token mode), returns:
On success, Status: 200 with:

{ "token" : "utk_0v6O8c6RsC9A5e2Fa9n5WX",
  "url" : "https://yourapp.com/login?token=utk_0v6O8c6RsC9A5e2Fa9n5WX"
}

On error, same type of response as Login.

When LoginRocket’s signup mode is user, returns same response as Login with &signup=true added to url.

When signup mode is user_token (Signup Token mode), returns:
On success, Status: 200 with:

{ "token" : "utk_0v6O8c6RsC9A5e2Fa9n5WX",
  "url" : "https://yourapp.com/login?token=utk_0v6O8c6RsC9A5e2Fa9n5WX"
}

On error, same type of response as Login.

When LoginRocket’s signup mode is user, returns same response as Login with &signup=true added to url.

When signup mode is user_token (Signup Token mode), returns:
On success, calls arSignupHandler with response object:

{ "token" : "utk_0v6O8c6RsC9A5e2Fa9n5WX",
  "url" : "https://yourapp.com/login?token=utk_0v6O8c6RsC9A5e2Fa9n5WX"
}

On error, same type of response as Login.

Initiate auth with social/external provider

Generates a URL, valid for 30 minutes, to a social or external authentication provider.

Returns a 302 redirect and a cookie, which must be provided by the client upon return from the external provider. Generally only useful for implementing in a web browser (or a webview in an app).

Note that URL does not begin with /v1.

Request

Example
GET /auth/:provider_type
GET /auth/:provider_id

# Examples:
GET /auth/facebook
GET /auth/ap_0v9XwmNDu1eHFAnDgYxHgb
curl https://sample.loginrocket.e1.com/auth/facebook
curl https://sample.loginrocket.e1.com/auth/ap_0v9XwmNDu1eHFAnDgYxHgb

Response

Example

Status: 302 with Location header.

Status: 302 with Location header.

Resend email token

Resends an email verification token. User’s email_verification must already be in requested state.

Request

Example
POST /v1/resend_email_token
{ "username" : "frank"
}
curl -X POST https://sample.loginrocket.e1.com/v1/resend_email_token \
  -d username=frank
$('#form').submit(function(event){
  AuthRocket.resendEmailToken({
    username: $("#field-username").val()
  }, arResendHandler);
  return false;
});

function arResendHandler(response){
  if (response.error) {
    $("#messages").text(response.error);
  } else {
    $("#messages").text(response.message);
  }
}

Response

Example

On success, Status: 200 with:

{ "message" : "A new verification email has been sent."
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, Status: 200 with:

{ "message" : "A new verification email has been sent."
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, calls arResendHandler with response object:

{ "message" : "A new verification email has been sent."
}

On failure, calls arResendHandler with response object:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

Verify email address

Verifies the user’s email address with an email token.

Request

Example
POST /v1/verify_email
{ "username" : "frank",
  "token" : "kvf_13uolkDJhdk"
}
curl -X POST https://sample.loginrocket.e1.com/v1/verify_email \
  -d username=frank -d token=kvf_13uolkDJhdk
$('#form').submit(function(event){
  AuthRocket.verifyEmail({
    username: $("#field-username").val(),
    token: $("#field-token").val()
  }, arVerifyHandler);
  return false;
});

function arVerifyHandler(response){
  if (response.error) {
    $("#messages").text(response.error);
  } else {
    $("#messages").text(response.message);
  }
}

Response

Example

On success, Status: 200 with:

{ "message" : "Your email has been verified."
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, Status: 200 with:

{ "message" : "Your email has been verified."
}

On error, Status: 200 with:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

On success, calls arVerifyHandler with response object:

{ "message" : "Your email has been verified."
}

On failure, calls arVerifyHandler with response object:

{ "error" : "All errors as sentences. And in a single string.",
  "errors" : [
    "All errors as sentences.",
    "But as an array of strings."
  ]
}

Questions? Find a Typo? Get in touch.