License

labelviewer has two products, licensed separately: the Viewer (the render API, <zpl-viewer> and labelviewer render) and the Editor (the merge API, <zpl-editor> and labelviewer merge). Your license key says which of them you have, until when, and for how many installations. It is one line of text (LV2.<payload>.<signature>), checked offline: nothing is sent anywhere.

Licenses at a glance#

Your key also states the number of installations it covers. Each running server shows its installation id on the Status page; keep the number of servers you run within your license (it is part of the license terms, not a technical limit). Set LABELVIEWER_INSTANCE_ID if you want a fixed id, e.g. for containers that are recreated often.

The evaluation license#

The download includes an evaluation (trial) license for both products, so everything works right away. On a trial license:

• every label image is watermarked: PNGs from the render API and labelviewer render, and the labels <zpl-viewer> shows, downloads and prints carry a repeated "TRIAL" text;
• <zpl-editor> shows a large X across the label on its canvas. The X is only drawn on screen: it is never part of the template, what you save, or what you export;
• merged ZPL (the merge API, labelviewer merge, the editor's exports) is never watermarked.

A trial license you receive from us works the same way; it may have an end date.

Install your license#

To switch to your production license, set one of these environment variables and restart labelviewer:

• LICENSE_KEY: the license key itself;
• LICENSE_FILE: the path of a file that holds it, for example a mounted secret (see the Docker examples).

As soon as one of them is set, that license decides, and the evaluation license is no longer used. The Status page (and GET /v1/info) shows the license in use: where it comes from (bundled evaluation license or configured license), whether it is a trial, the licensee, license id, products, expiry date and days left, the number of installations, and this installation's id. The server also logs one line about the license when it starts.

When a license expires or is not valid#

A license works through the end of its expiry date (UTC). There is no grace period: from the next day on, its products stop working until you install a renewed key. The same happens at once when the configured key is not valid (mistyped, truncated, or a LICENSE_FILE that cannot be read), and for a product your license does not include:

• the product's API routes answer 402 with an error code (license_required, license_expired or product_not_licensed) and a message that says what to do (API › Errors);
• labelviewer render / labelviewer merge exit with status 3 and print the same message;
• <zpl-viewer> / <zpl-editor> show "This label component is not licensed for this installation. Contact your administrator." instead of the label or the designer.

The developer portal, the Status page, /sdk/, GET /v1/info, /healthz, labelviewer version, labelviewer health and --help keep working, so you can always see why. A running server notices the expiry by itself (it checks at least once an hour and on every request) and logs it.

Before the expiry date there are no warnings in the components, the API or the CLI: check the Status page or GET /v1/info (license.daysLeft) in your monitoring, and renew in time.

Components and the license. <zpl-viewer> and <zpl-editor> ask the install they were loaded from (or their api-base) for its license when they start, and remember the answer for 10 minutes. If they cannot reach it (network down, or the SDK bundled into your app without api-base), they keep working and log one warning in the browser console: a temporarily unreachable server should not break your app, and the server's own API still enforces the license.

Questions#

• Does labelviewer contact you to check the license? No. The key is checked offline with a digital signature; nothing is sent anywhere. That also means it works in networks without internet access.
• How do I know when to renew? The Status page and GET /v1/info show the expiry date and the days left (license.daysLeft). There are no reminders in the components or the API, so add it to your monitoring.
• Can I move my license to another server? Yes: install the same key there and stop the old server. The key is not tied to a machine.
• Can I edit the key, e.g. to extend the date? No. Any change breaks the signature and the key is rejected.
• What is shown to my users when it expires? The components show "This label component is not licensed for this installation. Contact your administrator." Nothing else changes in your application.