docs: add IRIS API key runbook

Explains why the key rotated (IRIS_ADM_API_KEY was commented out in
iris-web/.env), documents the fix applied 2026-03-23, and provides
step-by-step procedures for key reset, container recreation, and
diagnosis when soc-integrator returns 401/502.

Also includes full service key inventory table.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/ops-runbook-iris-api-key.md

@@ -0,0 +1,112 @@
+# Runbook: IRIS Admin API Key — Keep It Static
+
+## Problem
+
+When the `iriswebapp_app` container is recreated, `post_init.py` runs on startup and sets
+the administrator's API key. If `IRIS_ADM_API_KEY` is **not** set in the env, it generates a
+**new random key** via `secrets.token_urlsafe(nbytes=64)`. This breaks the soc-integrator
+(HTTP 401 / 502) until the key is manually re-synced.
+
+**Root cause**: `iris-web/.env` line `IRIS_ADM_API_KEY` was commented out → random rotation
+on every container recreate.
+
+## Fix already applied (2026-03-23)
+
+`iris-web/.env` now has `IRIS_ADM_API_KEY` explicitly set to the current live key.
+`post_init.py` reads this env var and reuses it on every startup — no more rotation.
+
+---
+
+## If the key ever needs to be reset (e.g. suspected compromise)
+
+### Step 1 — Choose or generate a new key
+
+```bash
+python3 -c "import secrets; print(secrets.token_urlsafe(64))"
+```
+
+Note the output — this is `<NEW_KEY>`.
+
+### Step 2 — Update `iris-web/.env`
+
+```bash
+# Edit the file
+vi /home/tum/soc/iris-web/.env
+```
+
+Find and update the line:
+
+```
+IRIS_ADM_API_KEY=<NEW_KEY>
+```
+
+### Step 3 — Update soc-integrator
+
+```bash
+vi /home/tum/soc/soc-integrator/.env
+```
+
+Set:
+
+```
+IRIS_API_KEY=<NEW_KEY>
+```
+
+### Step 4 — Recreate both containers
+
+```bash
+# IRIS app (re-runs post_init.py with new key)
+cd /home/tum/soc/iris-web
+docker compose up -d --force-recreate app
+
+# soc-integrator (bakes new IRIS_API_KEY into container env)
+cd /home/tum/soc/soc-integrator
+docker compose up -d --force-recreate
+```
+
+> **Note**: `docker restart` does NOT re-read `.env` — you must use `--force-recreate`.
+
+### Step 5 — Verify
+
+```bash
+# 1. Confirm key in DB matches what you set
+docker exec iriswebapp_db psql -U postgres -d iris_db \
+  -c "SELECT api_key FROM \"user\" WHERE name='administrator';"
+
+# 2. End-to-end sync test
+cd /home/tum/soc
+python3 scripts/test-wazuh-iris-sync.py --no-send --minutes 60
+# Expected: all steps pass
+```
+
+---
+
+## Diagnosing a broken key (soc-integrator returning 502 / 401)
+
+```bash
+# Check integrator logs
+docker logs soc-integrator --tail=50 | grep -i "iris\|401\|502"
+
+# Read current key from IRIS DB
+docker exec iriswebapp_db psql -U postgres -d iris_db \
+  -c "SELECT api_key FROM \"user\" WHERE name='administrator';"
+
+# Compare with what soc-integrator has baked in
+docker exec soc-integrator env | grep IRIS_API_KEY
+
+# If they differ → follow steps 2-5 above (no need to generate a new key,
+# just re-sync the existing DB key into the two .env files)
+```
+
+---
+
+## Service key inventory (all static as of 2026-03-23)
+
+| Service | Credential | Location |
+|---------|-----------|----------|
+| IRIS admin API key | `IRIS_ADM_API_KEY` in `iris-web/.env` | Set statically; reused by `post_init.py` |
+| IRIS API key (integrator side) | `IRIS_API_KEY` in `soc-integrator/.env` | Must match IRIS DB value |
+| Wazuh API | `wazuh-wui` / password | `wazuh-docker/single-node/docker-compose.yml` env block |
+| Wazuh Indexer | `admin` / password | Same compose file |
+| Shuffle API key | `SHUFFLE_API_KEY` | `Shuffle/.env` + `soc-integrator/.env` |
+| Integrator internal key | `INTERNAL_API_KEY` | `soc-integrator/.env` |