Rotate the agent's authentication key

Agent keys can be rotated through the console without an observability gap. The cloud accepts both the new key and the previous key for a configurable grace window, so the deployment can roll over without strict synchronisation.

Steps

1. •

   Generate a new key

   In the console, open Agents, select the agent, then Rotate key. The cloud:

   1. Generates a new key, stores a hash of it, and returns the plaintext once.
   2. Retains the previous key's hash for a grace window (default: 24 hours from rotation), so the previous key keeps working until then.

   Copy the new key.

2. •

   Deploy the new key

   Update the agent's AGENT_KEY environment variable to the new value. The deployment path depends on your runtime:

   • Docker: docker run -e AGENT_KEY=<new> and restart the container.
   • Kubernetes: update the observer-agent Secret and roll the Deployment (kubectl rollout restart deploy/observer-agent).
   • systemd-managed Docker: edit /etc/observer-agent.env, then systemctl restart observer-agent.

   The agent reconnects with the new key on its next heartbeat.

3. •

   Confirm the rotation took effect

   Open the agent's dashboard. The Cloud panel reports a successful heartbeat with the new key. The Agents page in the console shows the agent as running with the new key fingerprint.

4. •

   Retire the old key

   The previous key automatically becomes invalid at the end of the grace window. To retire it sooner, open the agent in the console and set the grace window to zero. Subsequent requests with the previous key are rejected.

What the cloud sees

• The cloud stores a hash of each key, never the plaintext.
• The cloud stores a hash of the new key and retains the previous key's hash for the grace window.
• A request with the new key succeeds. A request with the previous key succeeds only until the grace window ends.
• A lost key cannot be recovered. Rotate to issue a replacement.