Telegraf Enterprise license enforcement

Telegraf Controller enforces two things based on your license status: how many resources you can create (scale limits) and which features are available. This page describes both kinds of enforcement and how license expiration affects them.

• Scale limits
• Enterprise feature gating
• License expiration lifecycle
• Response headers
• Reference: JWT claims

Scale limits

Telegraf Controller enforces a maximum number of configurations and a maximum number of reporting agents per instance.

The free-tier values are hardcoded into the Telegraf Controller binary and cannot be overridden.

What happens when a limit is reached

• “Create” endpoints (such as POST /api/configs) return 402 Payment Required with an error body identifying the resource, the current count, and the limit:

  {
    "error": "entitlement_limit_reached",
    "resource": "configs",
    "current": 20,
    "limit": 20,
    "message": "configs limit reached (20/20). Upgrade to Telegraf Enterprise for higher limits."
  }

• The corresponding create button in the Telegraf Controller UI is disabled and shows a tooltip explaining the limit.

• The response includes an X-Entitlement-Warning header (see Response headers).

A warning banner appears in the UI when usage reaches 80% of a limit so operators have advance notice before requests start being rejected.

Enterprise feature gating

A valid Telegraf Enterprise license unlocks the following features:

• Audit logging
• LDAP authentication
• OIDC authentication

API endpoints that require an enterprise feature return 403 Forbidden when called on a free-tier instance:

{
  "error": "feature_not_licensed",
  "feature": "audit_logging",
  "message": "audit_logging requires a Telegraf Enterprise license."
}

License expiration lifecycle

A license moves through four stages relative to its license_exp (contractual expiration) date:

The grace period is fixed at 14 days and is not configurable. Expiration status is re-evaluated hourly, so a status change takes effect within one hour without requiring a restart. To switch back to a valid status sooner, apply a renewed license through the UI. Uploads take effect immediately.

Response headers

Telegraf Controller adds the following headers to HTTP responses when the corresponding condition is true. Monitor these headers in deployment health checks to detect license-related issues before they affect users.

Reference: JWT claims

The following table describes the claims contained in a Telegraf Enterprise license JWT. Claims are informational. You don’t author license files yourself, but understanding what each claim controls helps when reading license details, scripting around licensing, or interpreting validation errors.