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.
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 |
|
email_confirmation |
string | Must match |
|
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 |
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.
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.
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;
}
}
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.
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;
}
}
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."
]
}
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.
Param | Value | Default | |
---|---|---|---|
token |
string | Login/session token. Optional, but recommended. |
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 = '/';
}
}
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."
]
}
Checks the validity of a login (session) token, which must be a full JWT.
Requires that the realm is using managed sessions.
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
}
}
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
}
Requests a password reset token.
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);
}
}
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."
]
}
Resets a password using a reset token.
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);
}
}
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."
]
}
Allows a user to update (change) their password.
Requires a valid login (session) token, which must be a full JWT.
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);
}
}
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.
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();
}
}
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.
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
.
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
Resends an email verification token. User’s email_verification
must already be in requested
state.
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);
}
}
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."
]
}
Verifies the user’s email address with an email token.
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);
}
}
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.