Running the service

You can install the Entitlements SDK either via Node.js or query using Https. After you configure the entitlements agent, you will need to install the SDK package so they can communicate.

Prerequisites

Configuring the agent is a prerequisite for completing the SDK installation.
To get started, select your technology from the following link: SDKs Overview, and navigate to the Entitlements section.

Installation with Node.js

To install the package using npm, run the following command:


$ npm install @frontegg/e10s-client

Initializing the client

import { EntitlementsClientFactory, RequestContextType } from '@frontegg/e10s-client';

const e10sClient = EntitlementsClientFactory.create({
	pdpHost: 'localhost:8181' // Entitlements Agent Host
});

Setting up the subject context

Subject context describes the user who performs the action; these can be taken from Frontegg JWT if authenticating with Frontegg.

const subjectContext: SubjectContext = {
	tenantId: 'my-tenant-id',
	userId: 'my-user-id', // Optional
	permissions: ['read', 'write'], // Optional
	attributes: { 'my-custom-attribute': 'some-value' } // Optional
};

Query

The Entitlements client allows you to query for a feature, permission, or route entitlement, each requiring different context information.

Querying for feature entitlement

const e10sResult = await e10sClient.isEntitledTo(
	subjectContext,
	{
		type: RequestContextType.Feature,
		featureKey: 'my-cool-feature'
	}
);

if (!e10sResult.result) {
	console.log(`User is not entitled to "my-cool-feature" feature, reason: ${e10sResult.justification}`);
}

Query for permission entitlement

const e10sResult = await e10sClient.isEntitledTo(
	subjectContext,
	{
		type: RequestContextType.Permission,
		permissionKey: 'read'
	}
);

if (!e10sResult.result) {
	console.log(`User is not entitled to "read" permission, reason: ${e10sResult.justification}`);
}

Querying for a route entitlement

const e10sResult = await e10sClient.isEntitledTo(
	subjectContext,
	{
		type: RequestContextType.Route,
		method: "GET",
        path: "/users"
	}
);

if (!e10sResult.result) {
	console.log(`User is not entitled to "GET /users" route, reason: ${e10sResult.justification}`);
}

Justifications

List of possible justifications:

Justification	Meaning
MISSING_FEATURE	User is missing the feature
MISSING_PERMISSION	User is missing the permission
PLAN_EXPIRED	User has a plan that covers the feature, but the plan is expired
MISSING_ROUTE	Requested route is not configured
ROUTE_DENIED	Requested route is configured to be blocked

Monitoring

In case monitoring mode is enabled, the result object will always return as follows (and in which the Entitlement check result will be 'logged'):

{
	"result": true,
	"monitoring": true
}

Querying via HTTPS

You can query the Entitlements Agent via HTTP.

If you are using Node.js, we recommend using its native SDK, as outlined above or in the repository to interact with the Agent.

Otherwise, please check the OpenAPI Specs for Entitlements Agent to get the full details on the exposed APIs.