Skip to main content
If you use the Codex CLI (or any other bearer-token-based MCP client) to talk to Hoard, you’re holding a long-lived API key in your shell environment. Sometimes you need to rotate it: an employee left, a laptop got lost, you suspect a leak, or you’re just doing a quarterly hygiene pass. This page is the clean rotation flow.

​
When you should rotate

  • A laptop or developer machine that had the key on it left your possession
  • An employee or contractor who had access to the key left
  • The key showed up in a chat log, a screenshot, or any place it shouldn’t have
  • It’s been more than 6 months and you’ve never rotated
  • You ran a security audit and a tool flagged the key
If you’re rotating because of a confirmed leak, also revoke any active OAuth connectors at the same time, see the bottom of this page.

​
What rotation does and doesn’t break

Breaks. Any client using the old bearer key stops working immediately. That’s the Codex CLI on your machine and any other CLI tools you’ve configured with the same key. Doesn’t break. OAuth-based connectors. Claude.ai and ChatGPT use OAuth, not your bearer key. They keep working through a rotation without any action on your part. The bearer key is only used by clients that can’t do OAuth, primarily the codex mcp CLI.

​
The rotation flow

​
Step 1: Regenerate your key

Open Settings → Account. Under API Key, click Regenerate key and confirm. This is a single revoke-and-reissue: the old key dies immediately and a fresh one takes its place. Any in-flight request using the old key returns an auth error on its next call. Your new 64-character hex key is shown right there under API Key — click reveal, then Copy. Save it to a password manager. Don’t email it to yourself, don’t paste it into a notes app that syncs to the cloud unencrypted. If you want to verify the old key is dead, try a hoard.sync.health call from a terminal that still has the old key — it should fail.

​
Step 2: Re-run the installer

The cleanest way to wire the new key into Codex is to re-run the one-line installer. On macOS or Linux:
On Windows, in PowerShell:
The installer asks for your bearer key (paste the new one), writes it to your shell rc file as HOARD_API_KEY, and re-registers the Hoard MCP server with Codex. It overwrites the old registration, so you don’t end up with two entries. If you prefer to do it by hand:
  1. Edit your shell rc file (~/.zshrc, ~/.bashrc, or PowerShell $PROFILE).
  2. Replace the old export HOARD_API_KEY="..." line with the new key.
  3. Open a new terminal so the new value takes effect.
  4. Run codex mcp list to confirm Hoard is still registered. If it’s not, re-add it:

​
Step 3: Verify

Open Codex and ask it to call a low-risk read:
“use hoard: run hoard.sync.health and tell me what comes back”
A healthy response means the new key is wired up and Codex is talking to Hoard.

​
Step 4 (only if you suspect a breach): rotate OAuth too

Bearer key rotation doesn’t touch OAuth. If you’re rotating because of a known leak or compromise, not just routine hygiene, also revoke OAuth:
  1. Open Settings → Connected apps.
  2. Click Revoke next to Claude and ChatGPT.
  3. Reconnect each one from their respective setup pages: Claude, ChatGPT.
This forces a fresh OAuth handshake, which gives each connector a brand-new token. Any token a leaked file might have referenced is now dead.

​
After rotation

A few things to check the next day:
  • Your activity log shouldn’t show any rejected_by_token outcomes from anywhere unexpected. If it does, somebody else’s tooling is still trying the old key.
  • Codex sessions you start fresh should work. Sessions that were already open before the rotation may need a restart to pick up the new env var.
  • If you put the old key into a CI environment or a teammate’s machine, update those too. The installer + a fresh HOARD_API_KEY in their shell profile is the same flow.

​
What to do if you forget which key is current

This happens. You set up a few machines and you can’t remember which key is in your shell. You hold one key at a time. The current one is always shown in Settings → Account under API Key — click reveal to read it, Copy to grab it. Compare it against what’s in your shell (echo $HOARD_API_KEY), or just regenerate to be certain you’re on a fresh key everywhere, then re-run the installer on each machine.