Token Rotation

Two types of secrets per agent can be rotated:

Secret	What if it leaks	When to rotate
agent_token	Attacker cannot forge (signing saves you) but gets registration rights	On suspicious network event, after admin departure
signing keypair	Attacker can forge if they also have the bearer token	After host compromise, periodically (annually)

Bearer Token Rotation

Via Dashboard

Settings → Agents → find the agent → click ↻ token → confirm.

The new token appears once in a green info box. Copy it, place it in /etc/monsys/agent.toml on the host, restart the agent.

Via API

NEW=$(curl -s -X POST -b /tmp/c.txt \
  https://api.monsys.ai/api/v1/agents/<agent-id>/rotate-token \
  | jq -r .token)

# On the host:
sudo sed -i "s|^agent_token =.*|agent_token = \"$NEW\"|" /etc/monsys/agent.toml
sudo systemctl restart monsys-agent

The old token is immediately invalid — there is no overlap window. If the agent does not come online with the new token within ~30 seconds, it will appear offline in the dashboard.

Audit Evidence

Each rotation writes a row to audit_log:

SELECT user_id, agent_id, event_type, created_at
FROM audit_log
WHERE event_type = 'agent_token_rotated'
ORDER BY created_at DESC;

Signing Key Rotation

The pinned pubkey on the hub is read-only for the agent — it cannot simply “upgrade” to a new keypair. An admin must first remove the pin:

Via Dashboard

Settings → Agents → click ↻ key → confirm.

Then on the host:

sudo rm /var/lib/monsys/agent-signing.key
sudo systemctl restart monsys-agent

The agent generates a new keypair and registers the new pubkey. The hub pins it again (TOFU). In the meantime, ingest payloads with the old signature are rejected (signature_invalid anomaly).

Via API

curl -s -X POST -b /tmp/c.txt \
  https://api.monsys.ai/api/v1/agents/<agent-id>/rotate-signing-key

Audit trail in audit_log: event_type='agent_signing_key_cleared'.

Recommended Rotation Cadence

Trigger	Token	Signing key
Periodic	annually	annually
Sysadmin departure	immediately	-
Host compromise suspected	immediately	immediately
Agent migration to new host	-	immediately
Disk image stolen / backup leaked	immediately	immediately

Rate Limits

Both endpoints are limited to 10 rotations per hour per user. Bulk-rotations (entire fleet after a security event) run over multiple hours — use a script with sleep 60 or schedule in a maintenance window.

What Does Not Rotate Automatically

There is currently no scheduled auto-rotation. A feature request for future versions. Until then: add a Linear / Jira ticket to your operations runbook with the desired cadence.