How do I install a license?

Requires Basic

Short answer

The product license isn’t uploaded — instead, it’s set as the environment variable LICENSE_KEY in the server configuration (.env); after restarting the backend, the new plan takes effect. You check the status under Administration → License — that’s also where you’ll find the Instance ID, which the vendor needs for an instance-bound license. Separately, you can conveniently set the plan of individual tenants in Tenant Management (the License Tier field).

Prerequisites

You need a license key issued by the vendor. For an instance-bound license, you first send the Instance ID (“Give this ID to your vendor for an instance-bound license. The license then runs only on this installation.”).

Open the license status. Administration → License (“Product license status for this installation: tier, limits and active modules.”). Without a key, the page shows “Community (no license)”.

Screenshot pending admin-module-lizenz-02 License section with tier, limits, active modules, instance ID, and validity

The license status: tier, 'Licensed to', 'Valid until', limits, and the instance ID.
Send the Instance ID (for a bound license). Copy the Instance ID from the License section and provide it when ordering. The issued key will then run exclusively on this installation (“Bound to this instance”).

Set the key. Enter the key in the server configuration and restart the backend:

# .env for the Notory installation
LICENSE_KEY="eyJwYXlsb2FkIjogIi…"   # full key on a single line

Check it. After the restart, Administration → License shows the new tier, “Licensed to”, “Valid until”, the limits, and the active modules.
Set the plan per tenant (optional, multi-tenant). In Tenant Management → Edit tenant you choose the tenant’s License Tier — e.g., a Basic tenant on an Elite installation.

There’s deliberately no API endpoint for installing the license (the key is server configuration). Reading it and setting tenant plans can be done via the API:

curl -H "Authorization: Bearer inv_dein_token" \
  https://demo.notory.io/api/v1/license

{
  "valid": true,
  "tier": "elite",
  "licensee": "ACME GmbH",
  "max_assets": 5000,
  "max_tenants": 50,
  "features": ["core", "assets", "network", "software", "licenses",
               "certificates", "compliance", "operations", "sso",
               "multi_tenant", "discovery", "provisioning", "webhooks",
               "custom_fields"],
  "expires_at": "2027-07-01T00:00:00+00:00",
  "reason": "License active",
  "in_grace": false,
  "instance_id": "1f0c9a7e3b5d48d2a6c4e8f0b2d4a6c8",
  "bound": true,
  "asset_count": 1873,
  "asset_limit_reached": false
}

curl -H "Authorization: Bearer inv_dein_token" \
  https://demo.notory.io/api/v1/entitlements

curl -X PUT https://demo.notory.io/api/v1/tenants/{tenant_id} \
  -H "Authorization: Bearer inv_dein_token" \
  -H "Content-Type: application/json" \
  -d '{ "license_tier": "professional" }'

Possible errors: 403 (tenant plan higher than the installation plan — “does not permit creating a tenant on the higher ’…’ plan”), 422 (unknown tier).

What happens behind the scenes?

Offline verification with a signature. The key is an RSA-signed package (tier, limits, features, “Licensed to”, expiry, optional instance binding). The backend verifies the signature offline against the bundled public key — it doesn’t phone home. Tampered or unreadable keys fall back to Community (“Invalid or unverifiable license”).
Instance binding. If the license carries an instance_id, it’s valid only on the installation with exactly that ID (“License is bound to a different installation” → Community). Notory generates the ID on first start and shows it in the License section.
Grace window after expiry. After the expiration date, the plan stays active for a grace period (in_grace: true) — the UI prompts you to renew. Only after that does the installation fall back to Community. Data is never deleted, only modules get locked and limits lowered.
Community as the fallback. Without a (valid) key: Core + Assets + Network, 30 assets, 1 tenant.
Tenant plan = intersection. A tenant’s plan is always capped by the installation license (both features and limits) — details under Understanding the limits.