License model

This page describes how entitlement is verified in v1.0.

---

The license is the source of truth

Entitlement comes from a signed license, not from local configuration. The product never treats a config flag or an environment variable as proof of entitlement on its own — it verifies the license cryptographically and reads the caps and expiry from it.

The license is a signed token (a JWT) signed with RS256. It carries, among other claims:

• the expiry (the license stops being valid after this date),
• a binding to this specific installation (so a license issued to one install cannot be replayed against another),
• the capacity caps — max_discovered_services and max_converted_services — that bound how much the install may discover and convert (see Capacity counting), and
• a license-format version that the verifier checks (the product accepts the current format version and rejects anything else).

---

Verification keys come from the Specaria platform (JWKS)

To check the license's signature, the product needs the platform's public verification keys. In the v1.0 design these are fetched from the Specaria platform as a key set (JWKS), rather than bundled statically into the product:

• The product fetches the key set from the platform over HTTPS and caches it (on the order of a day).
• Each key in the set has a key ID (kid). When the product sees a license signed with a kid it does not have cached, it refetches the key set to pick up newly-rotated keys.
• This means Specaria can rotate signing keys without requiring a product release — the fleet picks up new keys automatically on the next fetch or on the first kid miss.

Why not bundle the keys? Bundling verification keys into the binary (the earlier static-file predecessor's approach) makes key rotation a release event and risks a fleet-wide outage if a key ever needs to change in a hurry. The v1.0 design fetches keys instead. A bundled key still ships, but only as a bootstrap seed for the very first start before the platform has ever been reached — not as the long-term source of truth.

---

Periodic re-verification

Verification is not a one-time check at install. In the v1.0 design the product:

• verifies the license on every cold start, and
• re-verifies periodically during normal operation (on the order of once a day),

so that an expired, revoked, or tampered license is detected without waiting for a restart. Between re-verifications the result is cached briefly. If the platform is unreachable when a re-verification is due, the product falls back to the offline grace behaviour rather than failing immediately.

---

What a failed verification means

If the license signature does not verify, the license has expired, the installation binding does not match, or the format version is unsupported, the product fails closed for entitlement: licensed write operations are disabled (after any applicable offline grace window). This is the deliberate counterpart to telemetry, which fails open. See Offline grace for the staged behaviour and the licensing error codes.

Entitlement is never silently granted on a verification failure. A weak or missing key never causes the product to "assume licensed" — it surfaces an error instead.

---

One API key per (customer, product, environment)

Separate from the license itself, some Specaria-platform integration points are authenticated with a product API key. The rule is one key per (customer, product, environment) triple — a key issued for one environment must not be reused in another. Keys live in your environment's secret store (the build pipeline's secret manager for build-time integrations), never in the product database, and are rotated through the Specaria platform. Cross-environment reuse is forbidden.

---

Summary

| Element | v1.0 design | |---|---| | Entitlement source | Signed RS256 license (source of truth; never local config alone) | | Signature keys | Fetched from the Specaria platform (JWKS), cached, refetched on unknown key ID | | Re-verification | On every cold start + periodically (~daily) during runtime | | Format version | Verifier accepts the current format version; rejects others | | Install binding | License is bound to this installation; cannot be replayed elsewhere | | API keys | One per (customer, product, environment); no cross-environment reuse | | On failure | Fail closed for entitlement (after offline grace); never assume licensed |

---

All Specaria SOAP to REST docs