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:

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: If thatDot is temporarily unreachable, Novelty continues operating for a grace period to avoid downtime

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
  • Grace period: Days after expiration before shutdown (if included)
  • 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/admin/license-usage endpoint.

License Expiration

Novelty provides advance notice before license expiration through log warnings. If your license includes a grace period, Novelty continues operating for a limited time after expiration before shutting down.

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. Ensure your firewall allows:

Direction Protocol Port Destination
Outbound HTTPS 443 license-server.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-server.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.

java \
  -Dhttp.proxyHost=<PROXY_HOST> \
  -Dhttp.proxyPort=<PROXY_PORT> \
  -Dhttps.proxyHost=<PROXY_HOST> \
  -Dhttps.proxyPort=<PROXY_PORT> \
  -Dthatdot.novelty.license-key=<LICENSE_KEY> \
  -jar novelty.jar

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 extended period Check network connectivity; contact support
"Invalid license" License key is malformed or revoked 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).