Key Rotation
Rotate SAPIX_ROOT_KEY (instant) and SAPIX_MASTER_SEED (full migration procedure).
What you'll learn
- ✓Root key rotation: generate new → update compose → restart → update all services
- ✓Old root key stops working immediately after restart
- ✓Master seed rotation requires sapix-cli reencrypt before changing the env var
- ✓Danger: starting with new seed before migration makes data unreadable
- ✓Rotation best practice: maintenance mode → migrate → restart → verify
Rotate SAPIX_ROOT_KEY. Verify old key returns 401. Verify new key returns 200. Confirm all strand data is still accessible.
Interactive Walkthrough
What you'll learn
Rotate SAPIX_ROOT_KEY (instant) and SAPIX_MASTER_SEED (migration procedure).
Rotate SAPIX_ROOT_KEY (instant)
- Generate a new root key:
python3 -c "import secrets; print('spx_root_' + secrets.token_hex(32))" - Update
docker-compose.ymlwith the new value - Restart:
docker compose down && docker compose up -d - Update all services using the old key to the new key
The old key immediately stops working. All strand data is unaffected — this is just an auth credential.
Rotate SAPIX_MASTER_SEED (migration)
Master seed rotation re-encrypts all segment files. Steps:
`bash
# 1. Generate new seed
NEW_SEED=$(python3 -c "import secrets; print(secrets.token_hex(32))")
# 2. Run the re-encryption migration (sapix-cli) sapix-cli reencrypt \ --old-seed $SAPIX_MASTER_SEED \ --new-seed $NEW_SEED \ --data-path ./data/strand
# 3. Update docker-compose.yml with NEW_SEED
# 4. Restart
docker compose down && docker compose up -d
`
Never start the agent with a new seed before running the migration tool — data will be unreadable.
Challenge
Rotate your SAPIX_ROOT_KEY. Verify old key returns 401. Verify new key returns 200. Check that all strand data is still accessible.
---