monlet/docs/ops/token-rotation.md

Token rotation

Monlet uses split Bearer-token auth (ADR-0007):

• UI token — MONLET_AUTH_TOKEN env. Accepted by every UI/operator endpoint. The variable holds one or more space/comma-separated tokens; the server accepts any of them, so rotation is zero-loss.
• Agent key — generated locally by each agent and stored in state_dir/agent.key. It is not configured on the server; operators accept, block, remove, or blacklist keys through the Agents UI/API.

Rotate UI tokens independently from agent admission. Changing MONLET_AUTH_TOKEN does not affect accepted agents.

How multi-token overlap works

MONLET_AUTH_TOKEN is a list: tokens separated by spaces and/or commas. Examples:

MONLET_AUTH_TOKEN="single-token"
MONLET_AUTH_TOKEN="old-token new-token"
MONLET_AUTH_TOKEN="old-token,new-token"

All listed tokens are accepted. The middleware compares in constant time across the full list, so timing-side-channels do not leak which token matched.

Logs and metrics never include token values.

When to rotate

• Suspected UI token leak.
• Operator turnover.
• Routine schedule (e.g., quarterly).

Zero-loss procedure

1. Generate a new token:

   openssl rand -hex 32
   

2. Add the new token alongside the old one in the server environment:

   MONLET_AUTH_TOKEN="$OLD $NEW"
   

   Restart (or reload) the server. The old token still works, the new one is now accepted as well.

3. Move clients to the new token:

   • Update Web UI MONLET_API_TOKEN and restart.
   • Update any operator scripts or curl examples to use the new value.

4. Verify everything uses the new token:

   curl -sf -H "Authorization: Bearer $NEW" http://server:8000/api/v1/agents | jq .
   # Optional: tail server logs for unauthorized attempts during the window.
   

5. Remove the old token from the server environment:

   MONLET_AUTH_TOKEN="$NEW"
   

   Restart the server. From this point the old token is revoked.

6. Scrub the old value from secret stores, CI variables, and operator notes.

Notes

• Tokens are the only auth in v1; protect them like a database password.
• Tokens never appear in metrics labels, incident keys, or notification labels (ADR-0007, redaction policy).
• The server redacts Authorization/Cookie-style headers before logging (monlet_server/redaction.py).
• The middleware uses hmac.compare_digest against every accepted token; rotation does not introduce a timing oracle.
• To rotate an individual agent key, delete state_dir/agent.key on that host and restart the agent. The server will show a pending replacement for the same hostname; accept it after verifying the host.