Client API
The public, product-facing REST API (v1).
This REST API is the integration surface. The official SDKs wrap it unchanged.
Conventions
| Base URL | https://<portcullis-api-host>/api/v1 |
| Authentication | None at the HTTP level. Requests are authenticated by licenseKey (or licenseFileId) plus fingerprint in the body. |
| Content type | application/json |
| Request size | Bodies are limited to 16 KB. |
| Dates | ISO 8601 / RFC 3339 UTC strings, in and out |
| Request ID | An x-request-id header is echoed back. Log it; Digicom support can use it to find the request. |
| CORS | Not enabled. Call the API from your server-side code. |
| Rate limits | Per source IP: 60 requests per minute, and a lockout after repeated failures (by default 10 failures in 5 minutes → 15 minutes). Never per key. |
| Idempotency | Operations are naturally idempotent per fingerprint; retrying is safe. |
| Versioning | URI-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
| Field | Type | Required | Description |
|---|---|---|---|
productCode | string | Yes | Product code, for example "omnifleet" |
licenseKey | string | Activate: yes. Check-in / deactivate: this or licenseFileId | License key as entered by the operator |
licenseFileId | string | Check-in / deactivate: this or licenseKey | fid of the machine's current license file. Alternative credential after a license key rotation. Send it together with licenseKey. |
fingerprint | string | Yes | 64 hex characters, see Fingerprint |
nonce | string | Yes | base64url, 16–64 bytes, fresh for every request. Echoed in the returned license file. |
productVersion | string | No | For 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
| Field | Type | Required | Description |
|---|---|---|---|
hostname | string | Yes | Host name of the installation |
platform | string | Yes | For example "linux-x64" |
productBuildDate | string | No | Build date of this product version (RFC 3339) |
metadata | object | No | Extra 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
}
}| Field | Description |
|---|---|
licenseFile | Signed license file (mode: "online"). Verify before storing. |
machineId | ID of the machine record |
created | true if a new machine was created, false if this fingerprint was already activated |
Errors
| HTTP | code | When |
|---|---|---|
| 400 | VALIDATION_FAILED | Malformed body |
| 404 | LICENSE_NOT_FOUND | Unknown key, or key for another product |
| 403 | LICENSE_NOT_USABLE | License suspended, revoked, expired, or not yet started. Includes status. |
| 409 | MACHINE_LIMIT_REACHED | The license already has max_machines active machines. Includes current and max. |
| 429 | RATE_LIMITED | Too many requests; see the Retry-After header |
| 503 | SIGNING_UNAVAILABLE | The 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
| Field | Type | Required | Description |
|---|---|---|---|
usage | object of numbers | No | Actual usage keyed by feature code, for example { "limit.vehicles": 412 } |
metadata | object | No | Extra 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
| HTTP | code | When |
|---|---|---|
| 400 | VALIDATION_FAILED | Malformed body |
| 404 | LICENSE_NOT_FOUND | Unknown key or file ID, wrong product, or this fingerprint is unknown or deactivated on the license |
| 429 | RATE_LIMITED | Too many requests; see the Retry-After header |
| 503 | SIGNING_UNAVAILABLE | The 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
| HTTP | code | When |
|---|---|---|
| 400 | VALIDATION_FAILED | Malformed body |
| 404 | LICENSE_NOT_FOUND | Unknown key or file ID, wrong product, or unknown fingerprint |
| 429 | RATE_LIMITED | Too 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.