Skip to Content
PortcullisDocs
Reference

Client API

The public, product-facing REST API (v1).

This REST API is the integration surface. The official SDKs wrap it unchanged.

Conventions

Base URLhttps://<portcullis-api-host>/api/v1
AuthenticationNone at the HTTP level. Requests are authenticated by licenseKey (or licenseFileId) plus fingerprint in the body.
Content typeapplication/json
Request sizeBodies are limited to 16 KB.
DatesISO 8601 / RFC 3339 UTC strings, in and out
Request IDAn x-request-id header is echoed back. Log it; Digicom support can use it to find the request.
CORSNot enabled. Call the API from your server-side code.
Rate limitsPer source IP: 60 requests per minute, and a lockout after repeated failures (by default 10 failures in 5 minutes → 15 minutes). Never per key.
IdempotencyOperations are naturally idempotent per fingerprint; retrying is safe.
VersioningURI-versioned (/api/v1). The error code values are part of the public contract.

Response envelope

Success:

{ "status": "success", "data": { } }

Client error (4xx):

{ "status": "error", "data": { "message": "Human-readable message", "code": "LICENSE_NOT_FOUND" } }

Server error (5xx):

{ "status": "fail", "data": { "message": "Human-readable message" } }

Treat every 5xx and every network error as retryable, regardless of body.

Common request fields

FieldTypeRequiredDescription
productCodestringYesProduct code, for example "omnifleet"
licenseKeystringActivate: yes. Check-in / deactivate: this or licenseFileIdLicense key as entered by the operator
licenseFileIdstringCheck-in / deactivate: this or licenseKeyfid of the machine's current license file. Alternative credential after a license key rotation. Send it together with licenseKey.
fingerprintstringYes64 hex characters, see Fingerprint
noncestringYesbase64url, 16–64 bytes, fresh for every request. Echoed in the returned license file.
productVersionstringNoFor example "3.4.0"

POST /client/activate

Activates this installation (machine) on a license and returns a signed license file. Re-activating an already active fingerprint refreshes it and uses no extra seat.

Extra request fields

FieldTypeRequiredDescription
hostnamestringYesHost name of the installation
platformstringYesFor example "linux-x64"
productBuildDatestringNoBuild date of this product version (RFC 3339)
metadataobjectNoExtra diagnostic information

Request

{
  "productCode": "omnifleet",
  "licenseKey": "OMF-7KQ2M-HX9TB-P4WRN-3ZC8D",
  "fingerprint": "<64 hex chars>",
  "nonce": "<base64url>",
  "hostname": "omf-prod-01",
  "platform": "linux-x64",
  "productVersion": "3.4.0",
  "productBuildDate": "2026-10-01T00:00:00Z"
}

Response 200

{
  "status": "success",
  "data": {
    "licenseFile": "-----BEGIN PORTCULLIS LICENSE-----\n...\n-----END PORTCULLIS LICENSE-----\n",
    "machineId": "0193...",
    "created": true
  }
}
FieldDescription
licenseFileSigned license file (mode: "online"). Verify before storing.
machineIdID of the machine record
createdtrue if a new machine was created, false if this fingerprint was already activated

Errors

HTTPcodeWhen
400VALIDATION_FAILEDMalformed body
404LICENSE_NOT_FOUNDUnknown key, or key for another product
403LICENSE_NOT_USABLELicense suspended, revoked, expired, or not yet started. Includes status.
409MACHINE_LIMIT_REACHEDThe license already has max_machines active machines. Includes current and max.
429RATE_LIMITEDToo many requests; see the Retry-After header
503SIGNING_UNAVAILABLEThe product has no active signing key (Digicom operations issue)

POST /client/check-in

Refreshes the license file and reports version and usage. Call it every checkInIntervalHours (±10% jitter).

Extra request fields

FieldTypeRequiredDescription
usageobject of numbersNoActual usage keyed by feature code, for example { "limit.vehicles": 412 }
metadataobjectNoExtra diagnostic information

Request

{
  "productCode": "omnifleet",
  "licenseKey": "OMF-7KQ2M-HX9TB-P4WRN-3ZC8D",
  "licenseFileId": "0193f2c4-...",
  "fingerprint": "<64 hex chars>",
  "nonce": "<base64url>",
  "productVersion": "3.4.0",
  "usage": { "limit.vehicles": 412 }
}

Response 200

{
  "status": "success",
  "data": {
    "licenseFile": "-----BEGIN PORTCULLIS LICENSE-----\n...\n-----END PORTCULLIS LICENSE-----\n",
    "nextCheckInAt": "2026-11-15T09:00:00Z"
  }
}

If the license is suspended, revoked or expired, check-in still returns 200 with a signed file carrying that license.status (valid for 7 days). It never returns LICENSE_NOT_USABLE.

Errors

HTTPcodeWhen
400VALIDATION_FAILEDMalformed body
404LICENSE_NOT_FOUNDUnknown key or file ID, wrong product, or this fingerprint is unknown or deactivated on the license
429RATE_LIMITEDToo many requests; see the Retry-After header
503SIGNING_UNAVAILABLEThe product has no active signing key

POST /client/deactivate

Deactivates this machine and frees its seat. Delete the stored license file afterwards.

Request

{
  "productCode": "omnifleet",
  "licenseKey": "OMF-7KQ2M-HX9TB-P4WRN-3ZC8D",
  "licenseFileId": "0193f2c4-...",
  "fingerprint": "<64 hex chars>",
  "nonce": "<base64url>"
}

Response 200

{ "status": "success", "data": { "deactivated": true } }

Errors

HTTPcodeWhen
400VALIDATION_FAILEDMalformed body
404LICENSE_NOT_FOUNDUnknown key or file ID, wrong product, or unknown fingerprint
429RATE_LIMITEDToo many requests; see the Retry-After header

GET /client/keys/:productCode

Public signing keys for a product, used to build the keyring compiled into product releases. Do not use it to verify files at runtime.

Response 200

{
  "status": "success",
  "data": {
    "keys": [
      { "kid": "omf-2026-11", "algorithm": "Ed25519", "publicKey": "<base64url, 32 bytes>", "status": "active" }
    ]
  }
}

Returns keys with status active, pending and retired. publicKey is the raw 32-byte Ed25519 public key, base64url-encoded.

GET /client/time

Server time. Unsigned and informational only: products may show clock skew in diagnostics, but must never use it for validation.

Response 200

{ "status": "success", "data": { "now": "2026-11-14T09:00:00Z" } }

Error codes

See Error codes for the full list and handling advice.

On this page