License Validation (Offline, Telovix self-hosted)

Telovix self-hosted deployments require a signed license bundle imported into the Console. The Console validates this bundle offline using an embedded Ed25519 public key. No Telovix services connection is needed at validation time, during operation, or at sensor enrollment. Air-gapped deployments are fully supported.

For Telovix Cloud deployments, the license is injected automatically during Console provisioning. (Telovix Cloud only) Operators in that model never download, import, or manage a license file.

Prerequisites

• Telovix self-hosted Console already installed
• Signed license bundle downloaded from the Telovix Portal
• admin role to import the license

---

License bundle structure

A license bundle is a JSON file with this structure:

{
  "schema_version": 1,
  "signature_algorithm": "ED25519",
  "payload": {
    "customer_id": "<workspace_id>",
    "workspace_id": "<workspace_id>",
    "license_id": "lic-<uuid>",
    "supersedes_license_id": null,
    "plan": "growth",
    "max_protected_nodes": 250,
    "allowed_roles": ["admin", "manager", "analyst"],
    "support_tier": "priority",
    "valid_from": "2026-01-01T00:00:00Z",
    "valid_until": "2027-01-01T00:00:00Z",
    "grace_until": "2027-01-31T00:00:00Z",
    "issued_at": "2026-01-01T00:00:00Z",
    "console_id": null
  },
  "signature": "<base64-encoded-ed25519-signature>"
}

Payload fields

Field	Description
license_id	Unique identifier for this license bundle (format: lic-<uuid>)
supersedes_license_id	If this is a renewal, the previous license ID it replaces
plan	Plan name: trial, starter, growth, scale, or custom
max_protected_nodes	Maximum number of sensors the Console will allow to enroll
allowed_roles	User roles permitted in this deployment
support_tier	standard, priority, or professional
valid_from	License start time (RFC3339)
valid_until	License expiry time (RFC3339)
grace_until	Grace period end time; typically valid_until + 30 days
console_id	If set, the license is bound to a specific Console instance ID

Signature

The signature field contains a base64-encoded Ed25519 signature over the canonical JSON serialization of the payload object. The Console verifies this signature against the Ed25519 public key embedded in the Console binary at build time.

---

How the Console validates the license

When a license bundle is imported, the Console:

1. Parses the JSON envelope and extracts the payload and signature.
2. Serializes the payload back to canonical JSON.
3. Base64-decodes the signature.
4. Verifies the Ed25519 signature against the embedded public key.
5. If the signature is valid, stores the license and applies the entitlements.
6. If the signature is invalid, rejects the import with an error.

The Telovix Console does not contact Telovix servers during this process. The embedded public key is the only trust anchor. A license bundle from Telovix signed with the matching private key will always validate offline.

---

What the license governs

Node capacity

The max_protected_nodes field sets the upper limit on enrolled sensors. When this limit is reached, new sensor enrollments are blocked. Existing enrolled sensors continue operating and sending heartbeats. The AI assistant get_license_status tool reports the current node count against the limit.

Validity window and grace period

The license is active from valid_from to valid_until. After valid_until, the Console enters a grace period that lasts until grace_until (typically 30 days after expiry). During the grace period:

• Existing sensors continue operating normally
• New sensor enrollments may be blocked depending on the implementation state
• The Console displays an expiry warning in the UI

After grace_until, the license is fully expired. Consult the Console behavior when expired; the source confirms that expiry is tracked but the exact behavioral cutoff for each operation is not fully enumerated in the available source.

Console ID binding

If console_id is set in the payload, the license is bound to that specific Console instance. The Console validates the console_id field against its own configured instance ID. A mismatch causes the license to be rejected even if the signature is valid.

Workspace-level licenses (the common case for Telovix self-hosted deployments) have console_id: null and are not bound to a specific Console instance.

---

Obtaining a license

From the Portal

1. Log in to the Telovix Portal.
2. Navigate to your workspace Licenses page.
3. Click "Issue new license". Set valid_days (license duration) and grace_days (grace period after expiry, default 30).
4. Download the signed JSON bundle.

The Portal calls the license issuer service internally, which signs the bundle with the Ed25519 private key and returns the envelope. The resulting JSON file is what you import into the Console.

For deployment-specific licenses (bound to a console_id), use the deployment license endpoint from the Portal's Deployments section.

---

Importing a license into the Console

After Console installation and initial setup, import the license bundle using one of two methods.

Via the setup wizard (recommended for initial setup)

The Console setup wizard includes a license import step. Upload the signed .json bundle using the file picker in the wizard. The Console validates the signature and activates the entitlements before the wizard completes.

Via the Console Settings UI

To import a license, navigate to Settings > License in the Console and click Import License Bundle. Select the signed .json bundle from your workstation. The Console validates the signature and activates the entitlements immediately. No restart is needed.

Settings > License page showing the Import License Bundle button and the current license state after a successful import. Click to enlarge

Checking the current license state

In the Console, navigate to Settings > License to see the current plan, node limit, validity window, and lifecycle state.

---

License renewal

When you renew a license, the Portal issues a new bundle with supersedes_license_id set to the ID of the previous license. Import the new bundle the same way as the original - via Settings > License in the Console UI. The Console replaces the active license with the new one. The renewal does not affect enrolled sensors or active policy packs.

---

Expiry notifications

The Portal sends warning emails to the workspace owner before license expiry:

Trigger	Subject
30 days before expiry	"Telovix Portal: license expires in 30 days - {workspace_name}"
7 days before expiry	"Telovix Portal: license expires in 7 days - {workspace_name}"
After expiry	"Telovix Portal: license has expired - {workspace_name}"

Notification emails include the license ID, expiry date, and a link to the Portal license management page. The Portal background check for expiry runs every 6 hours. Users can opt out of license expiry notifications via the workspace notification preferences.

These notifications come from the Portal to the workspace owner's email. The Console itself does not send email; it displays an expiry warning in the UI based on the dates in the imported license payload.

---

Plan limits reference

Plan	Max protected nodes	Support tier
trial	5	standard
starter	100	standard
growth	250	priority
scale	500	professional
professional	50	professional
custom	10	professional

These limits are set by the Portal's plan_limits() function and encoded into each issued license at issuance time. The Console enforces max_protected_nodes from the license payload directly; it does not re-check the plan name.

---

AI assistant integration

The AI assistant get_license_status tool queries the current license state. In the Console, navigate to AI Assistant and ask "show current license status". The assistant returns the plan, node limit, current enrolled node count, validity window, and grace period status.

---

Operational guidance

Import the license during initial setup: The Console setup wizard includes a license import step. Without a valid license, enrollment may be restricted. Do not skip the license import step.

Plan renewals ahead of the expiry date: The grace period provides a 30-day buffer, but discovering an expired license during urgent sensor onboarding means waiting for Portal access. Download the renewal bundle before valid_until and have it ready to import.

Keep the license file secure: The license bundle is a signed entitlement artifact. Treat it like a credential: store it in a secrets manager or restricted directory, not in a public repository or general configuration store. The signature prevents forgery, but the bundle can be replayed by anyone who obtains it.

Air-gapped environments: Import the license from a machine that has Portal access, then transfer the JSON file to the Console host through your secure file transfer process. The Console validates entirely offline. See Air-Gapped Environments for full guidance.

---

Further reading

• Security Trust Model
• Console Installation
• Air-Gapped Environments
• AI Assistant