Licensing
Control Zero Self-Managed uses license keys for seat management and feature entitlement. License validation is performed entirely offline with no phone-home requirement.
License Key Format
License keys are issued as signed tokens with the following structure:
cz_ent_<base64-encoded-payload>
Each key encodes:
- Organization ID
- Seat count (maximum concurrent agents and users)
- Feature entitlements (Apps, Shadow AI, or both)
- Issue date
- Expiry date
- Cryptographic signature
The key is validated locally by verifying the embedded signature against the public key bundled with your installation. No network request is made during validation.
Seat Counting
Seats are counted based on unique active identities:
| Identity Type | How It Counts |
|---|---|
| API keys | Each active API key counts as one seat |
| Dashboard users | Each user with dashboard access counts as one seat |
| Scout agents | Each registered Scout agent counts as one seat |
Active means the identity has made at least one authenticated request in the current billing period (calendar month).
Inactive identities do not count against your seat limit. If you deactivate an API key or remove a dashboard user, the seat is released immediately.
Checking current usage
View seat usage in the dashboard under Settings > License, or via the management API:
curl -s https://localhost:8080/api/v1/license/usage \
-H "Authorization: Bearer <admin-token>" | jq
{
"seats_used": 12,
"seats_total": 50,
"api_keys_active": 8,
"dashboard_users": 3,
"scout_agents": 1
}
Expiry Behavior
When a license approaches or reaches its expiry date, the system follows a graduated enforcement model:
| Period | Behavior |
|---|---|
| 30 days before expiry | Warning banner in the dashboard. Warning-level log entries. |
| 14 days before expiry | Daily email notification to admin contacts (if email is configured). |
| Expiry date | Grace period begins. All features continue to work for 14 days. |
| Grace period ends (14 days after expiry) | Read-only mode. Policies continue to be enforced. New policy creation, user management, and configuration changes are disabled. Existing audit logging continues. |
Read-only mode ensures that governance enforcement does not stop due to an administrative lapse. Your existing policies and audit trails remain active.
Applying a License Key
During installation
czctl init --license-key cz_ent_<your-key>
After installation
Update the license key without restarting services:
czctl update-license cz_ent_<new-key>
The new key takes effect immediately. All services pick up the updated license within 60 seconds.
Via the dashboard
Navigate to Settings > License > Update License Key. Paste the new key and confirm.
Offline License Validation
License validation does not require network access. The validation process:
- Decodes the base64 payload from the key
- Verifies the cryptographic signature using the public key bundled with the installation
- Checks the expiry date against the local system clock
- Verifies seat entitlements against current usage
This means your self-managed deployment validates licenses without any external dependency. Ensure the host system clock is accurate (NTP within your internal network is recommended).
Renewal Process
- Contact your Control Zero account team or visit the enterprise admin portal to request a renewal.
- Receive a new license key with updated expiry and seat count.
- Apply the new key:
czctl update-license cz_ent_<new-key> - Verify the update in the dashboard under Settings > License, confirming the new expiry date and seat count.
No downtime is required for license renewal. The update is applied live.