These docs are for AuthRocket 1. Looking for AuthRocket 2 docs?

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

Field	Value	Req/Default	Notes
`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.

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."
  ]
}

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

Param	Value	Default
`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."
  ]
}

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.

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

JSON
Curl

Example

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.

Back to All Docs

Documentation

Knowledgebase

LoginRocket API

Fields

username and email

Confirmations

Login

Request

Example

Response

Example

Verify a 2FA login

Request

Example

Response

Example

Logout

Parameters

Request

Example

Response

Example

Check session token

Request

Example

Response

Example

Forgot password

Request

Example

Response

Example

Reset password

Request

Example

Response

Example

Update password

Request

Example

Response

Example

Signup

Request

Example

Response

Example

Initiate auth with social/external provider

Request

Example

Response

Example

Resend email token

Request

Example

Response

Example

Verify email address

Request

Example

Response

Example

`username` and `email`