On this page0
Unfamiliar word? See Glossary: words used in these docs. Looking for the tasks in order? Begin at Start Here.
Reference
Automated Provisioning
Once we have stood up your instance, it registers itself with the Zonitix licensing server (the store) to switch on the modules in your plan and receive security updates.
What Happens, In Order
There is nothing for you to do here. This page explains how a new instance switches on the modules in your plan. When we set up your instance, we place a one-time Provisioning Key in it; you never see it and there is nothing to copy or enter. The first time the instance starts, it shows that key to the Zonitix licensing server, which confirms the instance and switches on the modules in your plan.
Key Issued By Zonitix
When your instance is set up, Zonitix generates a temporary provisioning key for your license and places it in the instance. You never see or handle it.
First Start
The first time the instance starts, it presents that key to the Zonitix licensing server and asks to be registered.
Approval & Sync
Once Zonitix approves the instance, the instance collects its license and switches on the modules in your plan.
If something here is not working as you expect, start with When something goes wrong.
The plain explanation is above. This part is for IT and developers: the exact settings, permission names, API addresses and data fields behind it. Closed: select the heading above to open it. While it is closed, your browser’s find-on-page (Ctrl+F or Cmd+F) does not search this part.
The Two Handshake Calls
You never call these endpoints yourself; this section is for a reviewer who wants to see how an instance obtains its license secret. The handshake is two REST calls from your instance to the Zonitix licensing server. Both share the same limiter as the heartbeat — 10 requests per minute per source IP — and the instance stays well under it: it asks for the approval status on its five-minute license timer, and once more each time an administrator clicks Force Sync Heartbeat on the License & Entitlements screen.
// Step 1: Handshake Registration
POST /api/service/provision
Payload: { "provisioningKey": "TEMP_KEY", "companyName": "Zonitix Dev", "ipAddress": "127.0.0.1" }
Response: { "serviceId": "7b8f9e0d-...", "retrievalToken": "6a8b..." }
// Step 2: Poll Approval Status — POST, token in the JSON body
POST /api/service/provision/status/:id
Payload: { "retrievalToken": "6a8b..." }
Response (Pending): { "status": "PENDING" }
Response (Approved): { "status": "ACTIVE", "licenseKey": "MS-A1B2...", "licenseSecret": "hmac_secret_key", "licenseType": "Advanced" }
The short key { "t": "…" } is accepted as a synonym for retrievalToken. The service id may also be sent in the body as id or serviceId against the path-less form POST /api/service/provision/status. Failures: 401 for a missing, wrong or already-spent token, 404 for an unknown service id.
Two Rules That Protect The License Secret
The Retrieval Token Never Travels In A URL
The retrieval token is exchanged for the license secret, so it is accepted only in the JSON body of a POST. A query string is written into request logs along the way; a request body is not. The older form, GET /api/service/provision/status/:id?t=…, answers 410 Gone with a message naming the POST form, and does nothing else.
The Retrieval Token Works Once
While the service is still PENDING the token survives every status check. The first response that contains licenseSecret destroys it in the same request, so the secret is handed over exactly once. A later check answers 401 Unauthorized status check, because there is no stored token left to compare against. The provisioning key from step 1 is also spent by then, so a copied key or token cannot be replayed to obtain the secret a second time. If an instance ever loses its license secret, the only way back is for Zonitix to issue a fresh provisioning key so the handshake runs again. That is done by Zonitix, not by you.
Burning the token removes only that one key from the service configuration; feature flags and kill_switch are preserved untouched. The token is not included in config on heartbeat responses either; what those responses do carry is on Heartbeat (License Check-In).