License Verification

How your instance and the Zonitix licensing server (the store) prove to each other that a license check-in, and the answer to it, are genuine.

What The Signature Protects

The signature works in two directions. It protects us from someone pretending to be your instance in order to claim a plan: the store refuses any check-in whose signature does not match, and never logs the secret. It protects you from someone on the network forging or replaying the store’s answer to add or remove modules. It is not a seal on the software running on your server. We host that server, so the controls there are different ones: you cannot log in to the server itself, and every update is published by us and applied by your administrator.

If something here is not working as you expect, start with When something goes wrong.

A heartbeat with no signature is refused with 401, and one with a wrong signature with 403 that is logged as an HMAC mismatch against the license key.

Signature Construction

Both sides build the signing string from a fixed field order and HMAC it with your license secret. Order matters: a mismatch in field order produces a mismatched signature, so the array below has to be built in exactly this order wherever it is signed. Neither side writes the secret or the string that is signed to its logs. The store verifies a ten-field payload — the three telemetry values (appVersion, userCount, metrics) covered by the HMAC, where they previously travelled outside it. The instance we ship today signs all ten fields, so its telemetry travels inside the signature. Older instances that predate this change signed only the first seven fields (the identity fields plus timestamp), leaving their telemetry outside the signature; the store no longer accepts that payload (see below).

Three details decide whether your signature verifies:

• Absent telemetry is signed as null, not omitted. If your instance cannot read a metric this beat, put null in that slot — the store always signs ten positions.
• metrics must serialise identically in both places. The store HMACs its own JSON.stringify of the object it parsed out of your body, so the key order you send is the key order it signs. Build the object once and reuse it for the signature and the body; never re-order or re-emit it in between.
• Five of the six identity fields fall back to null on any falsy value (all but licenseKey, which is signed as-is). An empty-string hostname is signed as null by the store, so send null (or omit the field) rather than "".

metrics has up to three parts, and the whole object is one signed value. fleet is always present: for each platform and agent version, the number of enrolled devices and the number that checked in recently, as counts with no per-device rows; it is null when the counts could not be read. update is a short report of the release the instance runs and the result of its last update, added only when the instance holds one. deployKey is the public half of an SSH key pair made on your server, added only when the server has published one. Each part is described field by field on Heartbeat (License Check-In).

The Reply Is Signed Too

The entitlements the store returns are signed with the same license secret, and your instance verifies them before it writes a single flag. A reply that fails is discarded: the instance logs the rejection and keeps the entitlements it already holds, so a forged or replayed reply can neither unlock a module nor remove one. (The subscription-lapse pause is separate: it runs from the last paid-through date the instance verified, not from a discarded reply.)

• v2 is what a current instance checks. The HMAC must verify, nonce must equal the downlinkNonce this heartbeat sent, and seq must be greater than the last one accepted. The nonce is fresh for every beat, so a reply captured earlier cannot be replayed later.
• No downgrade. Once an instance has verified a v2 reply, a reply carrying only the older v1 signature is refused; once it has verified any signed reply, an unsigned one is refused.
• The paid-through date is trusted only from a signed reply. subscriptionExpiresAt sits inside the signed config, so it cannot be moved earlier or later in transit.

As with the request signature, this defends against the network, not against someone with root on the server, which Zonitix hosts.

Ten Fields Are Required

The store accepts only the ten-field signature. The legacy seven-field payload (the one that stopped at timestamp, leaving telemetry outside the HMAC) is refused with 403 INVALID_SIGNATURE. The instance we ship signs all ten fields, so this changes nothing for a current instance.

Why it changed: telemetry outside the HMAC meant anyone who observed one heartbeat could resend it inside the freshness window with fabricated appVersion, userCount or metrics, poisoning the append-only heartbeat history and the fleet view without ever holding your license secret.

The comparison is against the instant your instance signed, not our receive time, so it is immune to network delay — but it does mean the clock on your server has to move forward monotonically. The existing freshness window still applies on top: a timestamp more than 300 seconds either side of store time is rejected with 403 “Request expired”. A server whose clock drifts, or jumps backwards after a correction, will stall its own heartbeats until real time catches up to the last accepted value.