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/v1The 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
| # | Piece | Required | Guide |
|---|---|---|---|
| 1 | Configuration: PORTCULLIS_URL (default compiled in, overridable by environment variable), product code, keyring kid → publicKey compiled into the build, data directory on persistent storage | Yes | Key rotation, Containers |
| 2 | Fingerprint | Yes | Fingerprint |
| 3 | Activation screen: enter license key → POST /client/activate → verify and store file | Yes | Activation and check-in |
| 4 | License file verification | Yes | Verifying license files |
| 5 | State evaluation on startup and hourly | Yes | Enforcement guidelines |
| 6 | Check-in loop | If the license has a check-in interval | Activation and check-in |
| 7 | Offline activation | If the product is sold to air-gapped sites | Offline activation |
| 8 | Enforcement | Yes | Enforcement guidelines |
| 9 | Clock-tamper check | Recommended | Enforcement guidelines |
| 10 | Deactivate on decommission (POST /client/deactivate from an admin screen) | Recommended | Activation and check-in |
Files in the data directory
| File | Purpose |
|---|---|
<dataDir>/installation-id | Random UUID created on first run (unless PORTCULLIS_INSTALLATION_ID is set) |
<dataDir>/license.lic | The current signed license file |
<dataDir>/license.state | Clock-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 exampleOMF), - 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.