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 loginrocket.js, so if your client app runs in a web browser, you may want to use loginrocket.js instead (but you’re free to write your own code against the API if you prefer).

Initializing loginrocket.js

If using loginrocket.js, the LoginRocket client needs to be initialized before making any of the API calls below. You’ll need your AuthRocket Realm’s LoginRocket URL for this:

import LoginRocket from "@authrocket/loginrocket"
const loginrocket = new LoginRocket({
  url: "https://SAMPLE.e2.loginrocket.com/" // CHANGE to your own LoginRocket URL
})

See loginrocket.js for more.

Fields

email

In API methods that lookup users by email (login, forgot password, etc), the email field may also be a username or user ID (starts with usr_) instead.

Emails and usernames are case-insensitive. User IDs are case-sensitive.

password_confirmation

If present, confirmation will be always checked. If missing and not configured as required, the check will be bypassed.

API responses

Responses for direct API access and loginrocket.js are similar. Note that loginrocket.js normalizes nearly all responses including most errors, whereas direct API access will need to evaluate the HTTP status code as part of processing responses.

Using loginrocket.js

All requests return Promises.

See loginrocket.js responses for details on how to process responses. Our Getting Started - JS Logins example will also be helpful, in particular processResponse.

Direct API

HTTP status codes should be checked before attempting to parse or rely on the response payload.

Successful responses (HTTP status 2xx) return a JSON object with varied result types.

Field/data validation errors (status 409, 422) return a JSON object with a result of error and data-specific error messages. These error messages are localized.

All other 4xx and 5xx responses only return JSON on a best effort basis.

Result types

error
Contains field validation errors or similar. Messages are localized and safe to display to the user.

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

For loginrocket.js only, 4xx and 5xx errors (other than 409 and 422) are normalized into an error response similar to the above, with the addition of source. These error responses are generally not localized.

{ "result" : "error",
  "source" : "AccessDenied",
  "error" : "...",
  "errors" : ["..."]
}

source values:

• AccessDenied – 403: Session expired or access denied
• RecordNotFound – 404: Record or resource not found
• RateLimited – 429: Request was rate limited; wait before trying again
• LoginRocketError – All other errors

If not using loginrocket.js, rely on the HTTP status instead (as noted above under Direct API usage).

full_login
The user has fully logged in and all secondary conditions are satisfied. A full JWT login token is included and may be used to access your app.

{ "result" : "full_login",
  "token" : "a-full-JWT-login-token",
  "session" : "kss_SAMPLE",
  "account" : "org_SAMPLE"
}

Both account and session are included in the JWT token, so only token should need to be passed on to your app. They are included here to parallel conditional_login and for convenience when performing further account management via the LR API or LR Web.

conditional_login
The user has successfully authenticated, but one or more secondary conditions exist and require further action before being handed off to your app.

{ "result": "conditional_login",
  "conditions": ["see below"],
  "session": "kss_SAMPLE",
  "account": "org_SAMPLE"
}

To resolve the secondary conditions, you may either redirect the user to LR Web or handle them directly by using session and account with the appropriate LR APIs.

account contains the currently selected account ID, if available.

conditions will contain one or more of:

• account_inactive
• must_create_account (has 0 accounts)
• must_complete_profile (a now-required field is missing)
• must_setup_totp (must enroll in 2FA/TOTP)
• must_verify_email
• no_account_selected (has 2+ accounts and needs to select one)

Warning: your app should accept and rely on the full JWT token only. That is, it must not accept a bare session ID, otherwise the conditions here become unenforceable by LoginRocket.

need_mfa
Indicates that the login or login-like request was valid and now needs a 2FA/TOTP verification code. Typically this means to ask the user for their 2FA code and submit it with Verify a 2FA login.

{ "result" : "need_mfa",
  "token" : "a-temp-2fa-token-for-use-with-verify-login"
}

okay
Request was successful.

{ "result" : "okay",
  "message" : "..."
}

message is informational and generally confirms the action. API methods that aren’t user-initiated may not include it (see individual API method examples). If present, it is localized and suitable for display to the user.

Login

Authenticates a user using a password.

Request

POST /v2/login

{ "email" : "frank@example.com",
  "password" : "secret"
}

// on form submit
loginrocket.login({
  email: "frank@example.com",
  password: "secret"
}).then(response=>...)

Response

loginrocket.login({...}).then(response=>{
  // response.result is one of:
  //   conditional_login, error, full_login, need_mfa
})

Verify a 2FA login

Verifies a 2FA code and completes a password authentication.

Request

POST /v2/login/verify

{ "code" : "123456",
  "token" : "tmf:abc...xyz"
}

// on form submit
loginrocket.verifyLogin({
  code: "123456",
  token: "tmf:abc...xyz"
}).then(response=>...)

Response

{ "result" : "error",
  "error" : "...",
  "errors" : ["..."],
  "retryable" : true
}

loginrocket.verifyLogin({...}).then(response=>{
  // response.result is one of:
  //   conditional_login, error, full_login
  // when "error", also adds response.retryable.
})

Logout

Ends a login session.

session must be a session ID (starting with kss_), not a full JWT login token. This may be extracted from the sid claim of the JWT token, and also matches session obtained from Login and related methods.

Note: this method always returns success, whether or not session is valid.

Request

DELETE /v2/session

{ "session" : "kss_SAMPLE"
}

// on click
loginrocket.logout({
  session: "kss_SAMPLE"
}).then(response=>...)

Response

loginrocket.logout({...}).then(response=>{
  // response.result is one of:
  //   okay
})

Get session

Checks a login session, reevaluates secondary conditions, and issues a fresh token.

If a conditional_login result was returned previously, and after resolving those conditions, use this to reevaluate those conditions and convert session + account into a valid token.

Similarly, if the user wants to switch between accounts, sending the existing session and new account will return a new token specific to that account.

This can also be used to verify that an existing session is still valid.

Request

GET /v2/session

{ "account" : "org_SAMPLE",
  "session" : "kss_SAMPLE"
}

// on click
loginrocket.getSession({
  account: "org_SAMPLE",
  session: "kss_SAMPLE"
}).then(response=>...)

Response

loginrocket.getSession({...}).then(response=>{
  // response.result is one of:
  //   conditional_login, error, full_login
  if (response.error) {
    // session is invalid
  } else {
    // session is valid
  }
})

Forgot password

Requests a password reset token.

Request

POST /v2/password/forgot

{ "email" : "frank@example.com"
}

// on form submit
loginrocket.forgotPassword({
  email: "frank@example.com"
}).then(response=>...)

Response

{ "result" : "okay",
  "message" : "A password reset email has been sent. If you don't receive it within a few minutes, check your spam folder."
}

loginrocket.forgotPassword({...}).then(response=>{
  // response.result is one of:
  //   error, okay
  // if okay, includes result.message which may be displayed to the user.
})

Reset password

Resets a password using a reset token, then performs a user login.

Request

POST /v2/password/reset

{ "token" : "tpw:abc...xyz",
  "password" : "new-secret",
  "password_confirmation" : "new-secret"
}

// on load or form submit
loginrocket.resetPassword({
  token: "tpw:abc...xyz",
  password: "new-secret"
  password_confirmation: "new-secret"
}).then(response=>...)

Response

loginrocket.resetPassword({...}).then(response=>{
  // response.result is one of:
  //   conditional_login, error, full_login, need_mfa
})

Update password

Allows a user to change their password. If the user does not have a password (because they have only used social/external auth previously), allows them to set a password as well.

Requires a valid session ID.

Request

POST /v2/profile/password

{ "session" : "kss_SAMPLE",
  "current_password" : "old-secret",
  "password" : "new-secret",
  "password_confirmation" : "new-secret"
}

// on form submit
loginrocket.updatePassword({
  session: "kss_SAMPLE",
  current_password: "old-secret",
  password: "new-secret",
  password_confirmation: "new-secret"
}).then(response=>...)

Response

{ "result" : "okay",
  "message" : "Password updated."
}

loginrocket.updatePassword({...}).then(response=>{
  // response.result is one of:
  //   error, okay
  // if okay, includes result.message which may be displayed to the user.
})

Update profile

Allows a user to update their profile, including email, first_name, last_name, locale, or username. Only included fields are changed.

Requires a valid session ID.

Request

PUT /v2/profile

{ "session" : "kss_SAMPLE",
  "email" : "frank@example.io",
  "first_name" : "frank",
  "last_name" : "beans",
  "locale" : "en",
  "username" : "frank.n"
}

// on form submit
loginrocket.updateProfile({
  session: "kss_SAMPLE",
  email: "frank@example.io",
  first_name: "frank"
  last_name: "beans",
  locale: "en",
  username: "frank.n"
}).then(response=>...)

Response

{ "result" : "...",
  ...
  "token" : "fresh-login-token-with-updated-fields",
  "message" : "Profile updated."
}

loginrocket.updateProfile({...}).then(response=>{
  // response.result is one of:
  //   conditional_login, error, full_login
  // if conditional_login or full_login, includes result.message which may be displayed to the user.
})

Request an invitation

When signups are not publicly open, allows a prospective user to request an invitation.

Request

POST /v2/signup/request

{ "email" : "frank@example.com"
}

// on form submit
loginrocket.requestInvitation({
  email: "frank@example.com"
}).then(response=>...)

Response

{ "result" : "okay",
  "message" : "Thanks for your interest!"
}

loginrocket.requestInvitation({...}).then(response=>{
  // response.result is one of:
  //   error, okay
  // if okay, includes result.message which may be displayed to the user.
})

Signup

Creates a new user.

first_name, last_name, org_name, and username may all be disallowed, optional, or required, depending on your realm’s LoginRocket config. In some configurations org_name will default to the user’s name.

Parameters

Request

POST /v2/signup

{ "email" : "frank@example.com",
  "password" : "secret",
  "password_confirmation" : "secret"
}

// on form submit
loginrocket.signup({
  email: "frank@example.com",
  password: "secret"
}).then(response=>...)

Response

loginrocket.signup({...}).then(response=>{
  // response.result is one of:
  //   conditional_login, error, full_login
})

Verify email address

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

Request

POST /v2/email/verify

{ "token" : "tve:abc...xyz"
}

// on load or form submit
loginrocket.verifyEmail({
  token: "tve:abc...xyz",
}).then(response=>...)

Response

{ "result" : "okay",
  "message" : "Email successfully verified!"
}

loginrocket.verifyEmail({...}).then(response=>{
  // response.result is one of:
  //   error, okay
  // if okay, includes result.message which may be displayed to the user.
})