Skip to main content

Re-register a host (recover from a 401 / revoked key)

If a host's API key is revoked or otherwise rejected, the backend returns HTTP 401. The agent treats this as a serious event: it halts data forwarding and logs an explicit action. It does not auto-delete its credentials. That is a deliberate safety choice so a transient 401 can't accidentally de-register a host.

How you know​

In journalctl -u atherops-otel-agent:

level=error msg="authentication failed (401) — key may be revoked" action="halting; delete /etc/atherops/credentials.json to re-register"

On the Hosts page the host stops updating and goes offline after it misses heartbeats.

Recovery steps​

  1. Delete the stale credentials on the host:

    sudo rm /etc/atherops/credentials.json

  2. Generate a new install token in the AtherOps web app: Settings → Hosts → Install Token.

  3. Re-run the installer with the new token:

    curl -sSL https://releases.atherops.com/otel-agent/install.sh | sudo INSTALL_TOKEN=<token> bash

    The installer registers the host again, writes a fresh /etc/atherops/credentials.json (mode 0600), and restarts the service.

  4. Verify the host is back:

    systemctl status atherops-otel-agent
    journalctl -u atherops-otel-agent -f

    Look for registration complete and the host returning to online on the Hosts page.

A revoked key usually means the host should stop sending data until an operator intervenes. Auto-deleting credentials and silently re-registering could mask a real security event. The agent makes the recovery explicit and one command away.

See also​