Skip to Content
PortcullisDocs
Integrate (product engineers)

SDKs

The official Node.js and NestJS SDKs do activation, verification, check-ins, offline activation and entitlements for you.

The official SDKs implement everything in this guide — fingerprint, activation and check-in, verification, states, the clock-tamper check, offline activation and enforcement helpers — over the same client API and file format. REST integration keeps working; you can switch either way without any change on the server.

PackageForInstall
@portcullis-et/nodeAny Node.js product (18+). Also the portcullis CLI.npm install @portcullis-et/node
@portcullis-et/nestjsNestJS 10, 11 and 12 productsnpm install @portcullis-et/nestjs @portcullis-et/node

Both have zero runtime dependencies beyond Node (and Nest), ship ESM and CommonJS, and are tested against the published test vectors.

Node.js

import { Portcullis, PortcullisApiError } from "@portcullis-et/node";

const license = await Portcullis.create({
  productCode: "fleet",
  // Compiled into the build: the product's public keys (Products → Signing keys).
  keyring: { "fleet-2026-01": "<base64url Ed25519 public key>" },
  dataDir: "/var/lib/fleet/license", // persistent volume
  serverUrl: "https://api.portcullis.et", // env PORTCULLIS_URL overrides it
  productVersion: "2.3.0",
  checkIn: { usage: async () => ({ "limit.vehicles": await countVehicles() }) },
});
license.on("warning", notifyAdmins);
license.start(); // scheduled check-ins + hourly re-evaluation

// License screen
try {
  await license.activate(keyTypedByAdmin);
} catch (error) {
  if (error instanceof PortcullisApiError) showError(error.code, error.message);
  else throw error;
}

// Anywhere
if (!license.state.usable) enterReadOnlyMode(license.state.status);
if (license.isEnabled("module.trips")) mountTrips();
if (!license.withinLimit("limit.vehicles", vehicles + 1)) refuse("Vehicle limit reached");

Air-gapped sites:

const request = await license.createActivationRequest(); // → request.text, request.fileName (.req)
await license.importLicenseFile(licTextFromDigicom); // the .lic Digicom sends back

license.state.status is one of valid, valid_grace, not_activated, not_started, expired, suspended, revoked, invalid or clock_tampered; usable is true for the first two.

NestJS

@Module({
  imports: [
    PortcullisModule.forRoot({
      productCode: "fleet",
      keyring: KEYRING,
      dataDir: "/var/lib/fleet/license",
      serverUrl: "https://api.portcullis.et",
      isGlobal: true,
      globalGuards: true,
    }),
  ],
})
export class AppModule {}

@Controller("trips")
@RequiresFeature("module.trips") // 403 FEATURE_NOT_ENABLED unless licensed
export class TripsController {}

@Controller("license")
@SkipLicenseCheck() // the license screen keeps working when the license doesn't
export class LicenseController {
  constructor(private readonly license: PortcullisService) {}
}

With globalGuards, an unusable license puts the API in read-only mode: reads pass, writes get 403 LICENSE_NOT_USABLE, as the enforcement guidelines ask. PortcullisService also has health() for a Terminus-style health check.

CLI for operators

npx @portcullis-et/node doctor --product fleet --data-dir /var/lib/fleet/license --server https://api.portcullis.et
CommandWhat it does
portcullis fingerprintPrint this installation's fingerprint
portcullis requestWrite an offline activation request (.req)
portcullis import <file.lic>Import a license file received from Digicom
portcullis inspect <file>Show a .lic or .req (verifies with --keyring)
portcullis statusThe stored license and its state
portcullis doctorCheck the data directory, server reachability and clock skew

The full API reference is in each package's README on npm: @portcullis-et/node · @portcullis-et/nestjs.

Other languages

Only Node.js has an official SDK. Products in other languages integrate over the client API and must pass the test vectors.

On this page