Frontegg Node.js Client


Note regarding vesioning

  • As of version 3.0 and 4.0, we will no longer provide proxy middlewares
  • As of version 5.0.0, node 12 is no loner supported

To see an example implementation, head over to our
sample proxy project


Install the package using npm

# node 14+
npm install @frontegg/client


Frontegg offers multiple components for integration with the Frontegg's scaleable back-end and front end libraries

Initialize the frontegg context when initializing your app

const { FronteggContext } = require('@frontegg/client');


Redis cache

Some parts of SDK can facilitate the Redis cache for the sake of performance. To set up the cache, pass additional options
to FronteggContext.init(..) call.
If no cache is configured, then data is cached locally, in NodeJS process memory.

Redis cache with ioredis library

const { FronteggContext } = require('@frontegg/client');

}, {
  cache: {
    type: 'ioredis',
    options: {
      host: 'localhost',
      port: 6379,
      password: '',
      db: 10,

Redis cache with redis library

const { FronteggContext } = require('@frontegg/client');

}, {
  cache: {
    type: 'redis',
    options: {
      url: 'redis[s]://[[username][:password]@][host][:port][/db-number]',


Use Frontegg's "withAuthentication" auth guard to protect your routes.

A simple usage example:

const { withAuthentication } = require('@frontegg/client');

// This route can now only be accessed by authenticated users
app.use('/protected', withAuthentication(), (req, res) => {
  // Authenticated user data will be available on the req.frontegg object

Head over to the Docs to find more usage examples of the guard.

Access tokens

When using M2M authentication, access tokens will be cached by the SDK.
By default, access tokens will be cached locally, however you can use two other kinds of cache:

  • ioredis
  • redis

For details on cache configuration, refer to Redis cache section.


Frontegg provides various clients for seamless integration with the Frontegg API.

For example, Frontegg’s Managed Audit Logs feature allows a SaaS company to embed an end-to-end working feature in just 5 lines of code

Create a new Audits client

const { AuditsClient } = require('@frontegg/client');
const audits = new AuditsClient();

// initialize the module
await audits.init('<YOUR_CLIENT_ID>', '<YOUR_API_KEY>');

Sending audits

await audits.sendAudit({
  tenantId: 'my-tenant-id',
  time: Date(),
  user: '[email protected]',
  resource: 'Portal',
  action: 'Login',
  severity: 'Medium',
  ip: '',

Fetching audits

const { data, total } = await audits.getAudits({
  tenantId: 'my-tenant-id',
  filter: 'any-text-filter',
  sortBy: 'my-sort-field',
  sortDirection: 'asc | desc',
  offset: 0, // Offset for starting the page
  count: 50, // Number of desired items

Entitlements Client

Initializing the client

const { EntitlementsClient } = require('@frontegg/client');

// initialize the FronteggContext

// initialize entitlements client
const client = await EntitlementsClient.init(/* */);
await client.ready();

Using the client

The client can be used to determine if authorized user or tenant is entitled to particular feature or permission.

First, we need to validate its token, using the IdentityClient:

// validate token and decode its properties
const userOrTenantEntity = await identityClient.validateToken(token, { withRolesAndPermissions: true });

Note, that some JWT tokens might not contain permissions stored in their payloads. Permissions are essential for
entitlement decision-making, so remember to add option flag: withRolesAndPermissions: true.

(see Validating JWT manually section for more details).

When the user/tenant entity is resolved, you can start querying the entitlements engine:

const userEntitlementsClient = client.forUser(userOrTenantEntity);

let result;

// asking for feature entitlement
result = await userEntitlementsClient.isEntitledToFeature('foo');
// or
result = await userEntitlementsClient.isEntitledTo({
  featureKey: 'foo'

// asking for permission entitlement
result = await userEntitlementsClient.isEntitledToPermission('');
// or
result = await userEntitlementsClient.isEntitledTo({
  permissionKey: 'foo'

The result of those queries has the following structure:

type IsEntitledResult = {
  result: boolean,
  justficiation?: string

When result: true, then justficiation is not given.

Closing the client

To gracefully close the client:


Working with the REST API

Frontegg provides a comprehensive REST API for your application.
In order to use the API from your backend it is required to initialize the client and the
authenticator which maintains the backend to backend session

const authenticator = new FronteggAuthenticator();
await authenticator.init('<YOUR_CLIENT_ID>', '<YOUR_API_KEY>');

// You can optionally set the base url from the HttpClient
const httpClient = new HttpClient(authenticator, { baseURL: '' });

    email: '[email protected]',
    password: 'my-super-duper-password',
    // When providing vendor-host, it will replace(<...>) https://<api> with vendor host
    'frontegg-vendor-host': 'acme.frontegg',

Validating JWT manually

If required you can implement your own middleware which will validate the Frontegg JWT using the IdentityClient

First, let's import the IdentityClient

const { IdentityClient } = require('@frontegg/client');

Then, initialize the client

const identityClient = new IdentityClient({ FRONTEGG_CLIENT_ID: '<YOUR_CLIENT_ID>', FRONTEGG_API_KEY: '<YOUR_API_KEY>' });

And use this client to validate

app.use('/protected', (req, res, next) => {
  const token = req.headers.authorization;
  let user: IUser;
  try {
    user = identityClient.validateIdentityOnToken(token, { roles: ['admin'], permissions: ['read'] });
    req.user = user;
  } catch (e) {