Skip to Content
PortcullisDocs
Integrate (product engineers)

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 checkInIntervalHours with ±10% jitter. Also run at startup if the stored file's iat is older than the interval.
  • Send licenseKey and licenseFileId (= claims.fid of the stored file), fingerprint, a fresh nonce, productVersion, and an optional usage map. 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 to not_activated only after two consecutive 404s at least 1 hour apart.
  • Warn administrators when the stored file's exp is 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.

On this page