AuthRocket/Node.js

The authrocket-node npm covers all of our Core API. It also covers select portions of the Configuration API.

authrocket-node is for backend (server-side) apps. For frontend apps, see loginrocket.js.

If you’re using Express or a compatible framework, also see our streamlined integration available in authrocket-middleware.

For our Getting Started guide, see Integration with Node.js.

Installation

The library is designed to be installed using npm or yarn.

For installation, run one of:

npm install @authrocket/authrocket-node

yarn add @authrocket/authrocket-node

Client Basics

Using environment variables

If you are using environment variables to manage external services like AuthRocket, then it’s very easy to initialize the AuthRocket client:

import { AuthRocket } from '@authrocket/authrocket-node'
//  or
const { AuthRocket } = require('@authrocket/authrocket-node')

const authrocket = new AuthRocket()

Ensure these environment variables are set:

# If only validating tokens (including use with authrocket-middleware)
LOGINROCKET_URL    = https://SAMPLE.e2.loginrocket.com/

# If only validating tokens and default JWT key type has been changed to HS256
LOGINROCKET_URL    = https://SAMPLE.e2.loginrocket.com/
AUTHROCKET_JWT_KEY = SAMPLE

# To use the AuthRocket API
AUTHROCKET_API_KEY = ks_SAMPLE
AUTHROCKET_URL     = https://api-e2.authrocket.com/v2
AUTHROCKET_REALM   = rl_SAMPLE  # optional, but recommended (see below)
# plus LOGINROCKET_URL and/or AUTHROCKET_JWT_KEY if also validating tokens or using authrocket-middleware

AUTHROCKET_API_KEY = ks_SAMPLE
Your AuthRocket API key. Required to use the API (but not if only performing JWT verification of login tokens).

AUTHROCKET_JWT_KEY = SAMPLE
Used to perform JWT signing verification of login tokens. Not required if validating all tokens using the API instead. Also not required if LOGINROCKET_URL is set and RS256 keys are being used, as public keys will be auto-retrieved. This is a realm-specific value, so like AUTHROCKET_REALM, set it directly if using multiple realms (see below).

AUTHROCKET_REALM = rl_SAMPLE
Sets an application-wide default realm ID. If you’re using a single realm, this is definitely easiest. Certain multi-tenant apps might use multiple realms. In this case, don’t set this globally, but directly when constructing the client (see below).

AUTHROCKET_URL = https://api-e2.authrocket.com/v2
The URL of the AuthRocket API server. This may vary depending on which cluster your service is provisioned on.

LOGINROCKET_URL = https://SAMPLE.e2.loginrocket.com/
The LoginRocket URL for your Connected App. Used by authrocket-middleware (for redirects) and for auto-retrieval of RS256 JWT keys (if AUTHROCKET_JWT_KEY is not set). If your app uses multiple realms, you may need to set this directly instead (see below). If you’re using a custom domain, this will be that domain and will not contain ‘loginrocket.com’.

If you are using multiple realms, we recommend building a new client for each realm, directly setting realm, jwtKey, and/or loginrocketUrl:

const authrocket = new AuthRocket({
  realm:          'rl_SAMPLE',
  jwtKey:         'SAMPLE',
  loginrocketUrl: 'https://SAMPLE.e2.loginrocket.com/'
})

Similarly, if changing locales between requests, build a new client for each:

const authrocket = new AuthRocket({
  locale: 'es'
})

Direct configuration

It’s also possible to directly configure all AuthRocket client instance options:

const { AuthRocket } = require('@authrocket/authrocket-node')
const authrocket = new AuthRocket({
  apiKey:         'ks_SAMPLE',
  url:            'https://api-e2.authrocket.com/v2',
  realm:          'rl_SAMPLE',
  jwtKey:         'SAMPLE',
  loginrocketUrl: 'https://SAMPLE.e2.loginrocket.com/',
  locale:         'en'
})

Remember that it’s insecure to commit apiKey into your code. You may safely commit url, realm, and loginrocketUrl.

If jwtKey is an RSA key (starts with ‘MIIB’ or with ‘PUBLIC KEY’), it is also safe to commit. If it starts with ‘jsk’ or anything else, it is unsafe to commit with your code.

Requests

All requests return Promises and are compatible with async/await.

See the AuthRocket API documentation for available APIs, parameters, and responses, all with Node.js-specific examples.

Overview of common requests

Most resources support some or all of the below. Check specific APIs to confirm existence of specific functions.

List [resources]

// Retrieve multiple resources at once
let res = await authrocket.orgs.all()
res.results // Array of results
res.results[0].id // ID of the first returned resource

// Using Promise syntax instead of await
authrocket.orgs.all().then(res => {
  // ...
})

// Retrieve the first 20 resources
res = await authrocket.orgs.all({
  max_results: 20
})

// Retrieve the next 20 resources
if (res.hasMore()) {
  res = await authrocket.orgs.all({
    max_results: 20,
    after: rres.results[-1].id  // ID of the last resource previously received
  })
}

// A convenience function to retrieve the first resource when the ID isn't known.
// If there are no matching resources, returns null.
// Available for any resource that also offers all(), even if not documented separately.
let result = await authrocket.orgs.first()
result = await authrocket.orgs.first({
  state: "active"
})
result.id // ID of the returned resource

Get a [resource]

let result = await authrocket.orgs.find('org_SAMPLE')
result.id // ID of the returned resource
result.name // Name field of the returned resource
// throws a RecordNotFound exception if ID not found

result = await authrocket.orgs.find('org_SAMPLE', {
  ... // other arguments
})

Create a [resource]

let result = await authrocket.orgs.create({
  name: "Widgets Inc"
})
result.hasErrors() // true if there were errors
result.errors // array of error messages
result.errorMessages() // all error messages combined into one string
result.id // ID of the new resource

Update a [resource]

let result = await authrocket.orgs.update('org_SAMPLE', {
  name: "Widgets Inc"
})
result.hasErrors() // true if there were errors
result.errors // array of error messages
result.errorMessages() // all error messages combined into one string
result.id // ID of the updated resource
// throws a RecordNotFound exception if ID not found

Delete a [resource]

let result = await authrocket.sessions.delete('kss_SAMPLE')
result = await authrocket.orgs.delete('org_SAMPLE', {
  force: true
})
result.hasErrors() // true if there were errors
result.errors // array of error messages
result.errorMessages() // all error messages combined into one string
result.id // ID of the updated resource
// throws a RecordNotFound exception if ID not found

Responses

APIs that return multiple results will return those results as an array named results.

let res = await authrocket.orgs.all()
res.results // Array of results
res.results[0] // First result
res.hasMore() // Are there more results available?

APIs that return a single result access fields directly.

let result = await authrocket.orgs.find('org_SAMPLE')
result.id // ID of the returned resource
result.name // Name field of the returned resource

Errors and exceptions

Most errors are data validation errors (HTTP status 409 and 422). These errors are returned as part of result and need to be checked directly.

The most common exception will be RecordNotFound which is thrown when a resource cannot be found, generally when the ID doesn’t exist. Exceptions can also be thrown when hitting rate limits or encountering network errors.

import { AuthRocket, AuthRocketError, RecordNotFound } from '@authrocket/authrocket-node'
const authrocket = new AuthRocket()

// Using await
try {
  let result = await authrocket.orgs.update('org_SAMPLE', {
    name: "Widgets Inc"
  })
  if (result.hasErrors()) {
    // Use one of these to display/log the error messages
    result.errors // array of error messages
    result.errorMessages() // all error messages combined into one string
  } else {
    // success
  }
} catch (e) {
  if (e instance of RecordNotFound) {
    // ID not found
  } else if (e instance of AuthRocketError) {
    // all other possible AuthRocket exceptions
  } else {
    // non-AuthRocket exception
    throw e
  }
}

// Using Promises
authrocket.orgs.update('org_SAMPLE', {
  name: "Widgets Inc"
}).then(result => {
  if (result.hasErrors()) {
    // Use one of these to display/log the error messages
    result.errors // array of error messages
    result.errorMessages() // all error messages combined into one string
  } else {
    // success
  }
}).catch(e => {
  if (e instance of RecordNotFound) {
    // ID not found
  } else if (e instance of AuthRocketError) {
    // all other possible AuthRocket exceptions
  } else {
    // non-AuthRocket exception
    throw e
  }
})
Contents
Installation Client basics Requests Responses