rotate-secrets

name	rotate-secrets
description	Guided secret rotation with validation. Never revoke old key before new one is verified. Triggers: "rotate key", "change API key", "new token", "credential expired", "401 error".

Rotate Secrets

MANDATORY: Follow all 7 steps. Never revoke the old credential before the new one is verified working.

Step 1: Identify the Credential

Ask Trent which credential needs rotating, or determine from error logs. Reference table:

Credential	What It's For	Where to Get a New One
ANTHROPIC_API_KEY	Primary AI model	console.anthropic.com > API Keys
OPENAI_API_KEY	Fallback AI model	platform.openai.com > API keys
GEMINI_API_KEY	Fallback AI model	aistudio.google.com > Get API key
TELEGRAM_BOT_TOKEN	Agent messaging	BotFather on Telegram > /mybots > API Token
GITHUB_TOKEN	Memory sync	github.com > Settings > Developer settings > Personal access tokens
BRAVE_API_KEY	Web search	brave.com/search/api > Dashboard
SERPAPI_KEY	Search results	serpapi.com > Dashboard > API Key
PERPLEXITY_API_KEY	AI search	perplexity.ai > Settings > API
SHOPIFY_UK_ACCESS_TOKEN	UK store data	Shopify Admin (UK) > Apps > Custom apps
SHOPIFY_US_ACCESS_TOKEN	US store data	Shopify Admin (US) > Apps > Custom apps
SHOPIFY_AU_ACCESS_TOKEN	AU store data	Shopify Admin (AU) > Apps > Custom apps
META_ADS_ACCESS_TOKEN	Meta ad data	Meta Business Suite > System User > Generate Token
POLAR_API_KEY	Analytics	Polar Analytics dashboard > Settings > API
NVIDIA_API_KEY	AI model	build.nvidia.com > Settings > API Keys

Step 2: Generate New Credential

Guide Trent through the provider's dashboard:

• Tell him exactly which page to navigate to
• What buttons to click
• What to name the new key (if applicable)
• What permissions/scopes to select

IMPORTANT: Do NOT revoke the old credential yet. We need it as a fallback.

Step 3: Backup Current .env

ssh -i ~/.ssh/id_ed25519_github root@72.62.213.231 \
  "cp ~/.openclaw/.env ~/.openclaw/.env.backup-$(date +%Y%m%d-%H%M%S)"

Tell Trent: "Backed up the current secrets file. If the new key doesn't work, we can restore."

Step 4: Update the VPS

Ask Trent to paste the new credential value. Then update the .env file.

Option A (if Trent is comfortable with nano):

ssh -i ~/.ssh/id_ed25519_github root@72.62.213.231 "nano ~/.openclaw/.env"

Guide him: "Find the line that says [CREDENTIAL_NAME]=, delete the old value, paste the new one, then Ctrl+O to save and Ctrl+X to exit."

Option B (safer, using sed):

ssh -i ~/.ssh/id_ed25519_github root@72.62.213.231 \
  "sed -i 's|^CREDENTIAL_NAME=.*|CREDENTIAL_NAME=NEW_VALUE|' ~/.openclaw/.env"

After editing, verify permissions are still correct:

ssh -i ~/.ssh/id_ed25519_github root@72.62.213.231 "chmod 600 ~/.openclaw/.env"

Step 5: Restart and Validate

ssh -i ~/.ssh/id_ed25519_github root@72.62.213.231 "systemctl restart openclaw-gateway"

Wait 15 seconds, then check health:

ssh -i ~/.ssh/id_ed25519_github root@72.62.213.231 "openclaw gateway health"

Check logs for the specific provider:

ssh -i ~/.ssh/id_ed25519_github root@72.62.213.231 \
  "journalctl -u openclaw-gateway --since '2 min ago' --no-pager | grep -i [PROVIDER_NAME]"

If health check passes and no auth errors in logs, the new credential is working.

Step 6: Revoke Old Credential

ONLY after the new credential is verified working:

Tell Trent: "The new key is working. Now go back to [provider dashboard] and delete the old key. If the agent breaks in the next few minutes, we have the backup from Step 3."

Step 7: Update Rotation Log

Remind Trent to update docs/CREDENTIAL-ROTATION.md in the kurk-org repo with:

• Credential name
• Today's date
• Who rotated it

Special notes:

• SERPAPI: Both SERPAPI_KEY and SERPAPI_API_KEY must be set to the same value (the ClawdHub skill expects the second form)
• TELEGRAM_BOT_TOKEN: After rotating, the old bot token is immediately invalidated. Have the new one ready before changing.
• GITHUB_TOKEN: Must have repo scope for memory sync to work

Rules

• NEVER revoke the old credential before validating the new one works.
• NEVER display the full value of any credential. Use masking.
• ALWAYS backup .env before editing.
• ALWAYS verify the gateway restarts successfully after the change.
• If validation fails, restore from the Step 3 backup immediately:

  ssh -i ~/.ssh/id_ed25519_github root@72.62.213.231 \
    "cp ~/.openclaw/.env.backup-[TIMESTAMP] ~/.openclaw/.env && \
     chmod 600 ~/.openclaw/.env && systemctl restart openclaw-gateway"