====== 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.

===== Active flag =====

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.

===== Global API Key =====

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

  - Click **Regenerate** (the //refresh// button) to create a new random UUID
  - The Collector asks for confirmation - all agents using the **old** key will start to be rejected immediately after regeneration
  - 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.

==== When to regenerate ====

  * 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.

===== Per-System API Key Overrides =====

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

==== Add an override ====

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

==== Remove an override ====

  - Click the **trash** icon next to the row
  - 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)

===== How key match works =====

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

  - If the host is linked to a System **and** that System has an override key → the override must match
  - Otherwise → the global key must match
  - 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