License Verification and Entitlement Model

{/* AUTO-GENERATED from the docs pipeline — do not edit by hand /} {/ source doc_id: prd-s2r-docs-public-knowledgebase-licensing-license-model · version: 1.7.7 */}

Overview

Product entitlement is determined by a cryptographically signed license, not by local configuration flags or environment variables. The product verifies the license and reads capability limits and expiry dates directly from it. This model provides a dynamic and secure method for managing entitlements.

The license is a JSON Web Token (JWT) signed with the RS256 algorithm. It serves as the single source of truth for:

• The license expiration date.
• The specific installation the license is bound to.
• Capacity limits, such as max_discovered_services and max_converted_services.
• The version of the license format itself.

This platform-integrated model supersedes an earlier approach that relied on static license files bundled into the product binary.

How It Works

The license verification process involves fetching public keys from a central platform, validating the license token's signature, and periodically re-verifying it to ensure it remains valid.

Public Key Management

To verify a license's signature, the product requires the public keys of the central licensing platform. These keys are not bundled with the product. Instead, they are fetched dynamically.

1. Fetch and Cache: The product fetches a set of public keys (a JWKS, or JSON Web Key Set) from the licensing platform over HTTPS. It then caches this key set locally for a period on the order of one day.
2. Key Rotation: Each key in the JWKS has a unique Key ID (kid). When the product encounters a license signed with a kid that is not in its local cache, it re-fetches the entire JWKS from the platform. This mechanism allows the platform to rotate signing keys without requiring a product update or release.

A single public key is bundled into the product binary, but it serves only as a bootstrap seed for the very first startup before the product has successfully connected to the licensing platform. It is not used for long-term verification.

The following diagram illustrates the key fetching and license verification flow:

sequenceDiagram
    participant Product Instance
    participant Licensing Platform

    Product Instance->>Product Instance: Start-up or periodic check
    alt License key (kid) not in cache
        Product Instance->>Licensing Platform: GET /<JWKS_ENDPOINT>
        note right of Product Instance: The exact endpoint is not specified.
        Licensing Platform-->>Product Instance: Public keys (JWKS)
        Product Instance->>Product Instance: Cache public keys
    end
    Product Instance->>Product Instance: Verify license signature with cached key
    alt Verification Fails
        Product Instance->>Product Instance: Enter offline grace period
        Product Instance->>Product Instance: Disable licensed features
    else Verification Succeeds
        Product Instance->>Product Instance: Enable/continue licensed features
    end

Periodic Re-verification

License verification is not a one-time event. The product continuously ensures the license remains valid:

• On Cold Start: The license is verified every time the product starts.
• Periodically: The license is re-verified at a regular interval (approximately once per day) during normal operation.

The result of the verification check is cached briefly between re-verifications. If the licensing platform is unreachable when a check is due, the product enters an offline grace period rather than failing immediately.

License Token Claims

The license JWT contains several claims that define the terms of the entitlement. The source specifies the following claims, among others:

Product API Keys

Separate from the license token, certain integrations with the central platform are authenticated using a product API key. These keys follow a strict issuance and usage policy.

• Scope: One unique API key is issued for each (customer, product, environment) combination.
• Usage: A key issued for one environment (e.g., staging) must not be reused in another (e.g., production). Cross-environment reuse is forbidden.
• Storage: API keys should be managed in a secure secret store, such as the one provided by a build pipeline. They must never be stored in the product's database.
• Rotation: Keys are rotated via the central licensing platform.

Failure Modes

If a license verification fails for any reason, the product fails closed for entitlement. This means that licensed write operations are disabled after any applicable offline grace period has expired. Entitlement is never granted silently or by default if a check fails. This is in deliberate contrast to telemetry, which is designed to fail open.

Verification can fail under the following conditions:

• Invalid Signature: The license token's signature cannot be verified with the platform's public keys. This may indicate tampering.
• Expired License: The expiry date in the license has passed.
• Installation Mismatch: The license is bound to a different installation and is being replayed.
• Unsupported Format: The license format version is not recognized by the product.

In any of these cases, the product will surface an error and restrict functionality. For specific error codes, see Offline Grace.

Summary of v1.0 Design

See Also

• Licensing Overview
• Capacity Counting
• Offline Grace
• Egress Allow-list

All SOAP-to-REST docs