OS Agent - API Keys

The API Keys tab controls authentication between Telegraf agents and the Collector. Every push request must carry an X-API-Key HTTP header that matches a key configured here. Without a valid key, the Collector returns 401 Unauthorized and the metrics are dropped.

The Active checkbox at the top is the master switch for the OS Agent feature.

• Unchecked - all incoming pushes are rejected (401), no auto-discovery, no metrics in the pipeline. The push endpoint stays alive but answers unauthorized.
• Checked - pushes are accepted if the API key is valid.

After flipping this flag, click Save to apply.

The global API key is the default key used by every Telegraf agent unless an override exists for its System.

1. Click Regenerate (the refresh button) to create a new random UUID
2. The Collector asks for confirmation - all agents using the old key will start to be rejected immediately after regeneration
3. Use the eye button to reveal the key, the copy button to copy it to the clipboard

Important: Regenerating the global key invalidates every deployed agent that was using it. After regen, you must redeploy the new telegraf.conf (or just the new X-API-Key line) to all hosts.

• Initial setup
• Suspected leak (key exposed in logs, screenshots, repository, etc.)
• Periodic rotation, if your security policy requires it

A regenerated key is shown only once - it is also stored in the database so you can copy it again later from this tab.

In addition to the global key, you can give a dedicated key to a specific System. Useful when:

• One System is more sensitive and you want to rotate its key independently
• You want to revoke access for one System without touching the others
• Different teams own different Systems and you do not want to share keys

1. Pick a System in the dropdown at the top of the override section
2. Click Generate Override Key
3. The Collector creates a new UUID for that System and saves it
4. Use this key in the telegraf.conf of every agent attached to this System

1. Click the trash icon next to the row
2. The override is deleted - any agent that was using this key will be rejected on the next push, unless the global key is also accepted (see how match works below)

When a push arrives, the Collector resolves the System from the host's host tag (case-insensitive match against the connector hosts). Then:

1. If the host is linked to a System and that System has an override key → the override must match
2. Otherwise → the global key must match
3. If both fail → 401 Unauthorized and the request is dropped

In practice:

• A new agent on an unknown host always uses the global key (the host is not linked yet)
• Once you link the host to a System (in the Monitor tab) and create an override for that System, you must update the X-API-Key on the host