Skip to content

Managing Your Novelty License

Novelty uses a license key to verify your subscription and track usage against your entitlements. This guide explains how license verification works, what entitlements are available, and how to troubleshoot common issues.

License Key Basics

Obtaining a License Key

To obtain a license key:

Your Key Is Also Your Registry Credential

The same license key authenticates you to the private image registry that distributes the Novelty container image, registry.license.thatdot.com: the registry username is your client id, and the password is the license key itself. See the Helm Chart Quickstart for verifying access with docker and creating the Kubernetes image pull secret.

Protecting Your License Key

Your license key is tied to your organization, project, and environment. Treat it like a password:

Keep Your License Key Secure

  • Do not share your license key with others
  • Do not commit license keys to version control
  • Use environment variables or secrets management in production
  • Each deployment environment should have its own license key

How License Verification Works

Novelty verifies your license with thatDot:

  1. On startup: Novelty contacts thatDot to validate your key
  2. Periodically: Novelty checks in with thatDot at regular intervals
  3. Grace period: After a successful check-in, if thatDot is temporarily unreachable, Novelty keeps running for a grace period, including across restarts that keep the same data store. A first start against a new data store must reach thatDot, or Novelty shuts down.

Novelty requires an internet connection to validate your license. See Network Requirements for firewall configuration details.

Understanding Your Entitlements

Your license defines:

  • Expiration date: When your license expires
  • Monthly usage quota: Maximum consumption allowed per calendar month
  • Throttling: Whether rate limiting is enabled when approaching your quota

As you approach your usage quota, Novelty provides warnings and alerts to help you stay within your limits.

Usage-Based Licensing

Novelty tracks your consumption per calendar month. When usage approaches your monthly quota:

  1. Warning threshold: Log warnings appear indicating you're approaching your limit
  2. Alarm threshold: Log errors appear indicating you've exceeded your limit
  3. Throttling (if enabled): Consumption rate is reduced below the rate needed to use your monthly quota evenly

Monitoring License Usage

License Usage UI

Novelty includes a license usage dashboard that displays current and projected usage, license dates, and status information.

RBAC Requirement

The license usage dashboard and API require the Billing role when RBAC is enabled. See OIDC and RBAC Setup for details.

License Usage API

You can also query license usage programmatically via the License Usage: GET /api/v2/system/licenseUsage endpoint.

License Expiration

Novelty provides advance notice before license expiration through log warnings.

Contact sales@thatdot.com well before your license expires to arrange renewal.

Rotating License Keys

When you renew your license, the key typically remains the same and only the entitlements associated with it are updated. Key rotation is only necessary if your license key has been compromised.

To rotate your license key:

  1. Obtain your new license key from thatDot
  2. Update your configuration with the new key (see Novelty Setup)
  3. Restart Novelty to apply the new key

When using Helm, update the Kubernetes secret referenced by licenseKeySecret with your new license key, then perform a rolling restart. Each pod will pick up the new key as it restarts.

Network Requirements

Firewall Configuration

Novelty must be able to reach thatDot's license server and, unless telemetry is turned off, sends telemetry. Ensure your firewall allows:

Direction Protocol Port Destination Purpose
Outbound HTTPS 443 license.thatdot.com License validation and usage check-ins
Outbound HTTPS 443 improve.quine.io Telemetry

See Telemetry for what it sends and whether your license lets you disable it.

What Is Sent to the License Server

License validation and usage reports contain only:

  • Your license key
  • Product version and unique identification information
  • For each ingest: its model name, its ingest name, a numeric fingerprint (hash) of its transformation, and the number of records it has ingested
  • Timestamps

They never contain your hostnames or IP addresses, transformation text, ingested data, or model data. If your security review needs more detail, contact support@thatdot.com.

TLS Requirements

Novelty enforces strict TLS security when communicating with thatDot's license server:

  • TLS 1.3 required: Connections using older TLS versions are rejected
  • Certificate pinning: Novelty validates the license server's certificate against known public keys (SPKI pinning)

TLS Inspection Not Supported

Due to certificate pinning, Novelty cannot connect through proxies or network devices that perform TLS inspection (SSL interception). If your network uses TLS inspection, you must exempt license.thatdot.com or contact support@thatdot.com for guidance.

Proxy Configuration

If your network requires a proxy for outbound connections, configure Novelty with proxy settings. Only pass-through proxies that forward encrypted traffic without inspection are supported.

Configure the proxy directly in your Novelty configuration file:

thatdot {
  novelty {
    license-key = "YOUR_LICENSE_KEY"
    license-server-proxy-host = "proxy.corp.example.com"
    license-server-proxy-port = 8080
  }
}

Both license-server-proxy-host and license-server-proxy-port must be set for the proxy to activate. If only one is set, the proxy is not used and Novelty connects directly to the license server.

When the proxy is active, you will see a log message at startup: Configuring license server proxy: <host>:<port>

Note

Proxy authentication is not currently supported. If your proxy requires authentication, contact support@thatdot.com.

JVM Proxy Properties Do Not Apply

JVM-level proxy system properties (-Dhttps.proxyHost, -Dhttps.proxyPort, etc.) do not apply to license server traffic. Novelty manages license server TLS connections independently. You must use the application-level configuration above.

Troubleshooting License Issues

Common Error Messages

Error Cause Resolution
"License expired - shutting down" License has passed its expiration date Contact sales for renewal
"Grace period expired - shutting down" thatDot unreachable for longer than the grace period since the last successful check-in Check network connectivity; contact support
"License server contact failed - no persisted data - cannot retry: <detail>" License not validated on a first start against a new data store, so there is no grace period Check network connectivity and your license key; contact support
"License server returned error: <message>" thatDot answered the license check with an error, for example License token is invalid or License not found. Novelty then responds as it does when thatDot is unreachable Verify your license key; contact support
"License server certificate validation failed" TLS/certificate issue Check for TLS inspection; contact support

Connectivity Issues

If Novelty cannot reach thatDot, verify your network meets the Network Requirements above.

Getting Help

For license-related issues, email support@thatdot.com. Include your customer ID, error messages, and relevant log excerpts (with sensitive data redacted).