Skip to Content
PortcullisDocs
Integrate (product engineers)

Integration overview

What every product team must build to integrate with Portcullis over REST.

Products integrate with Portcullis over the REST client API and verify license files with the published file format. Node.js and NestJS products can use the official SDKs, which implement everything on this page; other products build it themselves, as described here.

All client endpoints live under:

https://<portcullis-api-host>/api/v1

The security of the whole system depends on your product verifying license files correctly. Never trust unsigned data, including HTTP status codes, to grant access.

Checklist

#PieceRequiredGuide
1Configuration: PORTCULLIS_URL (default compiled in, overridable by environment variable), product code, keyring kid → publicKey compiled into the build, data directory on persistent storageYesKey rotation, Containers
2FingerprintYesFingerprint
3Activation screen: enter license key → POST /client/activate → verify and store fileYesActivation and check-in
4License file verificationYesVerifying license files
5State evaluation on startup and hourlyYesEnforcement guidelines
6Check-in loopIf the license has a check-in intervalActivation and check-in
7Offline activationIf the product is sold to air-gapped sitesOffline activation
8EnforcementYesEnforcement guidelines
9Clock-tamper checkRecommendedEnforcement guidelines
10Deactivate on decommission (POST /client/deactivate from an admin screen)RecommendedActivation and check-in

Files in the data directory

FilePurpose
<dataDir>/installation-idRandom UUID created on first run (unless PORTCULLIS_INSTALLATION_ID is set)
<dataDir>/license.licThe current signed license file
<dataDir>/license.stateClock-tamper high-watermark (lastSeenAt), HMAC-protected

Before you start

You need from the Portcullis team:

  • your product code (for example omnifleet) and license key prefix (for example OMF),
  • the product's keyring (kid → public key) to compile into your build,
  • a test license key (see Testing with the demo product).

Then run the test vectors in your own test suite.

On this page