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 its hash, and returns the plaintext once.
   2. Demotes the previous key to previous_agent_key_hash with a previous_key_valid_until timestamp (default: 24 hours from rotation).

   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 previous_key_valid_until. 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 the SHA-256 of each key, never the plaintext.
• A request with the new key matches agent_key_hash and succeeds.
• A request with the previous key matches previous_agent_key_hash, and succeeds only while previous_key_valid_until is in the future.
• A lost key cannot be recovered. Rotate to issue a replacement.