Skip to main content

Licensing & Quotas

Terragnos Core ships as an enterprise, self-hosted platform. Every deployment must load a vendor-issued license that unlocks feature flags, module quotas, and contract metadata. This guide explains how to apply that license, keep it safe, and monitor enforcement signals.

What you receive from Terragnos​

Your entitlement package contains:

  • LICENSE_PUBLIC_KEY – the RSA public key that lets the API verify signed license payloads. This rarely changes.
  • LICENSE_KEY – an RS256-signed JWT that embeds the edition, feature list, tenant allowances, and expiration.
  • Optional support metadata (customer name, contract notes, contact info) for your own tracking system.

Customers never generate their own licenses. Any tooling under scripts/private exists solely for Terragnos staff when they issue or rotate keys.

Installation options​

1. Environment variables (preferred for automated deployments)​

Populate the values in the same location where you set database secrets:

LICENSE_PUBLIC_KEY=-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----
LICENSE_KEY=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...
LICENSE_STORAGE_SECRET=optional-symmetric-key-for-at-rest-encryption
  • LICENSE_STORAGE_SECRET encrypts the license when persisted in system_licenses. Use at least a 32-byte random string if you expect to rotate licenses or allow administrators to upload a new key through the API/UI later. Without it, the key only resides in memory and disappears on restart.
  • Restart the API and worker after updating these variables so they reload the entitlements.

2. API upload (for air-gapped or UI-driven workflows)​

When the API is already running, you can install or rotate a license through the admin endpoint:

curl -X POST \
  -H "Authorization: Bearer <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{ "licenseKey": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." }' \
  https://core.example.com/v1/license

The request must be authorized by a tenant owner or system administrator role. If LICENSE_STORAGE_SECRET is configured, the payload is encrypted before being stored; otherwise it remains in memory until the process restarts.

Use the console UI (Settings → License) for the same workflow if you prefer a graphical confirmation.

Verifying the active license​

Run GET /v1/license to confirm the currently applied edition, expiration, and quota profile:

curl -H "Authorization: Bearer <admin-token>" https://core.example.com/v1/license

The response includes:

  • status – valid, expiring_soon, or expired.
  • edition – e.g., enterprise, gov, or a custom contract name.
  • features – boolean map for modules (automation, advanced layers, etc.).
  • limits – numeric ceilings for object_count, workflow_run_count, query_count, and any bespoke counters.
  • metadata – issuer and tenant annotations for audit purposes.

Quotas and enforcement​

Every write path (object create/update/delete, workflow transitions, automation run effects, query jobs) updates the relevant tenant_usage_counters entry and checks it against the limit attached to the license. When a limit would be exceeded:

  1. The API responds with HTTP 403 License limit exceeded plus the limitCode (for example, object_count).
  2. A corresponding audit event (license.limit_exceeded) is written so you can trace when the ceiling was hit.
  3. Prometheus metrics (license_limit_exceeded_total{limitCode}) increment for alerting.

Plan for headroom by periodically reviewing GET /v1/license and the metrics surfaced by the worker exporter. Terragnos will issue an updated license when you upgrade tiers or request additional capacity—follow the installation steps above to swap it in.

Rotation and expiry​

  • Rotation: When you receive a new key before the old one expires, either update the environment variables and restart or POST the new key via the API/UI. The service validates the signature and immediately switches to the new entitlements.
  • Grace period: Licenses typically include a built-in grace status. Monitor the status field; when it transitions to expiring_soon, plan the rotation.
  • Expired state: Once status=expired, all limited operations return 403 until a valid key is installed. Read-only endpoints continue to function so you can export data.

Best practices​

  1. Store the license bundle in your organization’s secret manager alongside other production credentials.
  2. Restrict access to the /v1/license endpoints to tenant owners or infrastructure administrators.
  3. Set up alerts on license_limit_exceeded_total and any expiring_soon status to avoid unexpected outages.
  4. Keep the public key in the same configuration management system as the rest of your infrastructure so you can rotate it quickly if Terragnos provides a new verification key.

Need help applying or rotating a license? Contact Terragnos support with your deployment fingerprint (visible in /v1/license) and the team will issue updated keys.