Activation and check-in
Activate online, keep the license fresh with check-ins, and deactivate on decommission.
Base URL: https://<portcullis-api-host>/api/v1. All bodies are JSON. Full request and
response details are in the Client API reference.
Every request carries a fresh random nonce (16 bytes, base64url). The returned license file echoes it; reject the file if it doesn't match. This prevents replay of old responses.
Activate
Called from your activation screen after the operator enters the license key.
curl -sS -X POST "https://<portcullis-api-host>/api/v1/client/activate" \
-H "Content-Type: application/json" \
-d '{
"productCode": "omnifleet",
"licenseKey": "OMF-7KQ2M-HX9TB-P4WRN-3ZC8D",
"fingerprint": "<64 hex chars>",
"nonce": "<16 random bytes, base64url>",
"hostname": "omf-prod-01",
"platform": "linux-x64",
"productVersion": "3.4.0",
"productBuildDate": "2026-10-01T00:00:00Z"
}'import { randomBytes } from 'node:crypto';
import os from 'node:os';
// PRODUCT_CODE, PRODUCT_VERSION, PRODUCT_BUILD_DATE, KEYRING and DATA_DIR are your build/config values.
const PORTCULLIS_URL = process.env.PORTCULLIS_URL ?? 'https://<portcullis-api-host>/api/v1';
export async function activate(licenseKey: string, fingerprint: string) {
const nonce = randomBytes(16).toString('base64url');
const res = await fetch(`${PORTCULLIS_URL}/client/activate`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
productCode: PRODUCT_CODE,
licenseKey,
fingerprint,
nonce,
hostname: os.hostname(),
platform: `${process.platform}-${process.arch}`,
productVersion: PRODUCT_VERSION,
productBuildDate: PRODUCT_BUILD_DATE,
}),
});
const body = await res.json();
if (body.status !== 'success') {
// body.data.code: LICENSE_NOT_FOUND, MACHINE_LIMIT_REACHED, LICENSE_NOT_USABLE, ...
throw new ActivationError(body.data.code, body.data.message);
}
const { licenseFile } = body.data;
const claims = verifyLicenseFile(licenseFile, KEYRING); // see "Verifying license files"
if (claims.product.code !== PRODUCT_CODE) throw new Error('wrong product');
if (claims.machine.fingerprint !== fingerprint) throw new Error('fingerprint mismatch');
if (claims.nonce !== nonce) throw new Error('nonce mismatch');
saveAtomically(`${DATA_DIR}/license.lic`, licenseFile);
return claims;
}Success response:
{
"status": "success",
"data": {
"licenseFile": "-----BEGIN PORTCULLIS LICENSE-----\n...\n-----END PORTCULLIS LICENSE-----\n",
"machineId": "0193...",
"created": true
}
}created is false when this fingerprint was already a machine on the license (re-activation
is free and does not use another seat).
Show the operator a clear message for each error code, see Error codes.
Check-in
Run a check-in loop when claims.license.checkInIntervalHours is not null.
- Run every
checkInIntervalHourswith ±10% jitter. Also run at startup if the stored file'siatis older than the interval. - Send
licenseKeyandlicenseFileId(=claims.fidof the stored file),fingerprint, a freshnonce,productVersion, and an optionalusagemap. The server accepts either the current key or a known file ID, so check-ins keep working after Digicom rotates the license key. - On 200: verify the file (including the nonce), then replace the stored one atomically (write a temp file, then rename). Re-evaluate the state.
- On a network error or 5xx: retry with exponential backoff, starting at 1 minute and doubling up to 1 hour. Keep the current file. Never change state because of a network error.
- On 404 (
LICENSE_NOT_FOUND): switch tonot_activatedonly after two consecutive 404s at least 1 hour apart. - Warn administrators when the stored file's
expis less than 7 days away.
curl -sS -X POST "https://<portcullis-api-host>/api/v1/client/check-in" \
-H "Content-Type: application/json" \
-d '{
"productCode": "omnifleet",
"licenseKey": "OMF-7KQ2M-HX9TB-P4WRN-3ZC8D",
"licenseFileId": "<claims.fid of the stored file>",
"fingerprint": "<64 hex chars>",
"nonce": "<16 random bytes, base64url>",
"productVersion": "3.4.0",
"usage": { "limit.vehicles": 412, "limit.users": 37 }
}'export async function checkIn(stored: Claims, licenseKey: string, fingerprint: string) {
const nonce = randomBytes(16).toString('base64url');
const res = await fetch(`${PORTCULLIS_URL}/client/check-in`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({
productCode: PRODUCT_CODE,
licenseKey,
licenseFileId: stored.fid,
fingerprint,
nonce,
productVersion: PRODUCT_VERSION,
usage: { 'limit.vehicles': await countVehicles() },
}),
});
if (res.status >= 500) throw new RetryableError(); // back off, keep current file
const body = await res.json();
if (body.status !== 'success') return handleClientError(res.status, body.data);
const claims = verifyLicenseFile(body.data.licenseFile, KEYRING);
if (claims.nonce !== nonce || claims.machine.fingerprint !== fingerprint) {
throw new Error('unexpected license file');
}
saveAtomically(`${DATA_DIR}/license.lic`, body.data.licenseFile);
return { claims, nextCheckInAt: body.data.nextCheckInAt };
}Success response:
{
"status": "success",
"data": {
"licenseFile": "-----BEGIN PORTCULLIS LICENSE-----\n...\n-----END PORTCULLIS LICENSE-----\n",
"nextCheckInAt": "2026-11-15T09:00:00Z"
}
}Suspension and revocation arrive as signed files
If Digicom suspends, revokes or lets a license expire, check-in still returns 200 with a
signed file whose license.status is suspended, revoked or expired. Store it and
evaluate the state as usual. Keep checking in, so a reinstatement or renewal is picked up.
Deactivate
Offer a Deactivate action in the product's admin screen for decommissioning a server. It frees the seat so the license can be activated elsewhere.
curl -sS -X POST "https://<portcullis-api-host>/api/v1/client/deactivate" \
-H "Content-Type: application/json" \
-d '{
"productCode": "omnifleet",
"licenseKey": "OMF-7KQ2M-HX9TB-P4WRN-3ZC8D",
"licenseFileId": "<claims.fid of the stored file>",
"fingerprint": "<64 hex chars>",
"nonce": "<16 random bytes, base64url>"
}'On { "status": "success", "data": { "deactivated": true } }, delete the stored license file.
The product is then not_activated.