License Administration

What an administrator can see and do about licensing on your instance: read the license status, ask for a check-in now, and reset. Activation and the alert thresholds are managed by Zonitix and are not set from the instance.

Where This Lives In The Product

In the app, open System → License & Entitlements. It shows the license status and plan, the features your plan includes, and a heartbeat health card with the number of missed check-ins, the grace time remaining and the two alert thresholds — those are read-only and labelled “Managed by Zonitix; shown here for reference”. There are two buttons:

• Force Sync Heartbeat — runs one check-in now. While the instance has not managed to register, the same button reads Retry registration.
• Emergency License Reset — clears the license state and switches off every module that depends on your plan. Only someone on the administrator role can complete it.

There is no control for entering a provisioning key and none for editing the thresholds.

When Someone Needs To Step In

Your instance is activated automatically: it registers with the Zonitix licensing server (the store) using the provisioning key we place on it when we build it, then checks in every five minutes, and the store answers with the features your plan includes. The two buttons exist for two moments: a manual re-check after a network outage, and clearing license state on a server that is being handed back. Both are written to the audit log.

What Happens When A Subscription Lapses

Separately from missed check-ins, the instance pauses paid modules when the subscription itself has ended. This is the full rule; other pages link here. Each verified reply from the store carries a signed paid-through date. Paid modules are paused only when all of these hold:

• a paid-through date from a signature-verified store reply is on record;
• that date is more than 14 days in the past;
• the store has answered your instance since that date. An instance that simply cannot reach the store is never paused on this rule;
• the rule is in force on the instance.

If the date is missing or unreadable, or any of the conditions cannot be read, the instance treats the subscription as not lapsed.

• During the 14 days: nothing is paused.
• After them: requests to the modules that depend on your plan are refused with the message “Your subscription has lapsed. Premium features are paused until it is renewed — your data and core features remain available.”
• Never paused: the core modules that carry no license flag, your data, and the Report Engine. Links already sent to people outside your company keep working too: a document out for signature, a candidate’s portal and self-scheduling links, and the webhooks that complete them.
• Who is told: the app shows a banner to administrators and to anyone whose role lets them manage security settings. During the 14 days it names the date the subscription ended and the date the pause begins; once paused it says premium modules are paused. Closing it hides it for that browser session; it returns when the state changes.
• To restore: renew. The next verified heartbeat delivers the new signed date and the modules resume.

The status fields behind this rule and the refusal code are in the technical part below, under Subscription Lapse: Status Fields And Refusal.

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

The screen is at /dashboard/license; the page and its menu entry need the manage_security permission. Force Sync Heartbeat is the same action as POST /license/sync and reads Retry registration while the status is PROVISIONING_FAILED; Emergency License Reset is the same action as POST /license/reset. The warning a run of failures produces is GRACE_EXPIRED, and heartbeatHealth.featuresDisabled in the status payload is always false. The fingerprint logged for the provisioning key is the first 8 characters of its SHA-256.

The Endpoints

All five are mounted under /license in the user-management service and reached through the gateway at /api/v1/user-management/license. Every call needs an authenticated session. The read is granted to three permissions. Of the four writes, only sync is a working action for a manage_security holder: reset additionally requires the administrator role, and the other two are retired and always refuse.

GET /license — Status

The one read. It takes no body and returns the instance’s licensing picture assembled from SecuritySetting rows: the handshake status (UNPROVISIONED → PROVISIONING_FAILED → PENDING_APPROVAL → ACTIVE), the resolved licenseType, the mapped features, host/seat figures from the last beat, the heartbeatHealth block, and the subscription block — the one that tells an admin a pause is coming before anything changes.

seats and host are informational: recommended is a sizing hint computed from the server’s CPU and memory, and nothing on the instance caps the number of users.

Activation Is Automatic — POST /license/provision Is Retired

There is no manual activation step. The provisioning key is injected into the instance as a secret when we build it; the background license service registers with it on its own and then polls until the store approves the instance. Watch GET /license: status reads PROVISIONING_FAILED while a key is present but registration has not yet succeeded, moves to PENDING_APPROVAL once the store has accepted the registration, and to ACTIVE only after the store approves the service and a later sync retrieves the permanent license key and secret. It does not go straight to ACTIVE.

The old endpoint for typing a key in by hand still exists so that the contract is explicit rather than silent, but it does nothing: every call answers 410 "Manual provisioning is disabled. This instance is activated automatically by the store." and writes a LICENSE_PROVISION_REJECTED audit line (warning) with the caller’s IP address. Whatever body you send is ignored.

POST /license/sync — Force A Heartbeat

Takes no body. Runs one heartbeat immediately rather than waiting up to five minutes for the next scheduled beat — the action to use after fixing outbound connectivity, or right after approval to pull the license down now. In the app this is the Force Sync Heartbeat button. The reply carries the store’s config object. Note that config is null when there is nothing to sync yet (no keys, or still waiting on approval), and the endpoint still returns 200.

What Sync Actually Writes

On a 200 heartbeat the instance first checks the store’s signature on the reply (see License Verification). A reply that fails that check is discarded and the instance keeps what it already holds. A reply that passes is persisted to SecuritySetting rows that the rest of the app reads:

• Feature flags. Every store config key is stored raw as remote_<key>, and the mapped ones are also written to the local flag the feature routes actually enforce. The mapping is fixed — there is no dynamic key discovery:

training used to ride on the HR records flag. Until the store sends a training value of its own, GET /license reports features.training from hris.

• Tier + host figures. license_type is set from licenseType or config.tier; host CPU/RAM, recommended seats, and seats-used are saved for the status read.
• Paid-through date. The subscription date inside a signed reply is saved; it is the only input to the lapse rule described below. An unsigned reply never writes it.
• Strike clock reset. A success clears the failure count, the first-failure marker, and the grace state back to OK — one good beat is a full reset.
• Agent trust bundle. If the store returned latestTrustBundle, it is stored in SecuritySetting.agent_trust_bundle (see below).
• Advertised agent releases. macOS/Linux/Windows releases are persisted only after their vendor signature verifies against the pinned key — the store is treated as a catalog, not a trust anchor. A bad or missing signature leaves the last-known-good untouched.
• Container reconcile request. A marker file is dropped for the host updater agent when an entitlement changed, and once on the first successful heartbeat, so that a new instance’s running services are trimmed to its plan. The agent starts or stops the matching containers with no redeploy.

Strike / Grace Thresholds — Read-Only

Two thresholds decide how a run of missed heartbeats escalates. They are managed by Zonitix and cannot be changed from the instance; the License & Entitlements page shows them for reference, and GET /license returns them as heartbeatHealth.policy.

• warnStrikes — consecutive failed beats before the connection is reported degraded. Default 3.
• graceHours — hours since the first failure before the grace window is reported expired. Default 336 (14 days).

POST /license/heartbeat-policy is intentionally disabled. Every call, whatever the body, answers 403 "Heartbeat policy is managed by Zonitix and cannot be changed from this instance." and writes a LICENSE_HEARTBEAT_POLICY_BLOCKED audit line (warning). Nothing is stored.

Worked Example: Strike → Warn → Degrade

Beats run every 5 minutes. Take the defaults, warnStrikes: 3, graceHours: 336, and suppose the store becomes unreachable at 09:00:

So warnStrikes sets how fast a blip becomes a WARNING (3 strikes ≈ 15 minutes at the 5-minute beat), and graceHours sets how long the instance may run unverified before the state becomes the loud GRACE_EXPIRED. Strikes must be consecutive — a single successful beat resets everything. The bias is deliberately toward the customer: the overwhelmingly likely cause of a failing heartbeat is our side (store down, DNS, blocked egress), so the strike policy only ever raises alarms, it never enforces.

Subscription Lapse: Status Fields And Refusal

The rule itself is in the plain part above, under What Happens When A Subscription Lapses. These are the identifiers behind it.

• What counts as an answer from the store: an HTTP reply from the store counts, except the gateway-type statuses 502, 503, 504 and 520–530, which are treated as coming from the network in front of the store; a timeout does not count either.
• Whether the rule is in force: the status field subscription.enforced reports it.
• During the 14 days: subscription.state reads grace and subscription.graceEndsAt holds the date the pause would begin.
• After them: subscription.premiumPaused is true, and requests to plan-gated modules answer 402 "Subscription lapsed".
• Who sees the banner: administrators and anyone whose role holds manage_security.

POST /license/reset — Clear State

Administrator role only. Holding manage_security is not enough: any other caller is refused with a 403, and the handler’s own second check answers 403 "Only an administrator can reset the licence." with a LICENSE_RESET_DENIED audit line (warning). In the app this is the Emergency License Reset button.

Takes no body. Wipes the license key, license secret, service id, provisioning key, auto-provision flag, last-heartbeat markers, and license type; clears the strike/grace clock (an unprovisioned instance is not “degraded”); and sets every store-mapped feature flag to an explicit false, so all license-gated features go dark. The flags are set to off rather than deleted because the feature routes treat a missing flag as allowed. It returns 200 "License reset successfully" and writes a LICENSE_RESET audit line (warning). The next verified heartbeat after the instance is activated again rewrites every flag with its real entitlements.

The Same Beat Carries Agent-Key Revocation

Licensing is not the only thing riding the store heartbeat. When the store answers a beat it may include latestTrustBundle — the vendor trust bundle that carries agent release-key revocation. Sync persists it verbatim into SecuritySetting.agent_trust_bundle, and device-service serves it to your enrolled agents on their own check-in. This is the path by which a compromised or retired agent signing key is revoked fleet-wide.