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:

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:

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

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

Response

Example

On success, status 200 with result of conditional_login, full_login, or need_mfa.
On error, status 422 with result of error.

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

See Result Types.

Verify a 2FA login

Verifies a 2FA code and completes a password authentication.

Request

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

Response

Example

On success, status 200 with result of conditional_login or full_login.
On error, status 422 with result of error and additional key retryable:

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

retryable indicates if token may be reattempted. If false, start over with a fresh login.

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

retryable indicates if token may be reattempted. If false, start over with a fresh login.
See Result Types.

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

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

Response

Example

On all requests, status 200 with result of okay.

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

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

Response

Example

On success, status 200 with result of conditional_login or full_login.
On invalid session, status 403 with result of error.

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

See Result Types.

Forgot password

Requests a password reset token.

Request

Example
POST /v2/password/forgot
{ "email" : "frank@example.com"
}
// on form submit
loginrocket.forgotPassword({
  email: 'frank@example.com'
}).then(response=>...)

Response

Example

On success, status 200 with result of okay.

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

On error, status 422 with result of error.

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

See Result Types.

Reset password

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

Request

Example
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

Example

On success, status 200 with result of conditional_login, full_login, or need_mfa.
On error, status 422 with result of error.

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

See Result Types.

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

Example
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

Example

On success, status 200 with result of okay.

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

On error, status 422 with result of error.

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

See Result Types.

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

Example
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

Example

On success, status 200 with result of conditional_login or full_login along with message.

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

On error, status 422 with result of error.

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.
})

See Result Types.

Request an invitation

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

Request

Example
POST /v2/signup/request
{ "email" : "frank@example.com"
}
// on form submit
loginrocket.requestInvitation({
  email: 'frank@example.com'
}).then(response=>...)

Response

Example

On success, status 200 with result of okay.

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

On error, status 422 with result of error.

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

See Result Types.

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

ParamValueDefault
email string Email address'
first_name string User's first/given name
last_name string User's last/family name
org_name string Account/organization name
password string
password_confirmation string

Must match password if present. Always allowed; required if so configured.

username string Username or alias for the user.
invitation invitation_token Optional if public signups are open, required if closed.

Request

Example
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

Example

On success, status 200 with result of conditional_login or full_login.
On error, status 422 with result of error.

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

See Result Types.

Verify email address

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

Request

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

Response

Example

On success, status 200 with result of okay.

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

On error, status 422 with result of error.

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

See Result Types.