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 → Profile. 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: Wire the new key into Codex

Update 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:
Or use the installer. Sign in, open https://www.tryhoard.com/install/codex, and paste the one-line command into your terminal. The command carries a signed link that is valid for one hour and works from any terminal — no browser session needed. The script writes the key to your shell rc file as HOARD_API_KEY and re-registers the Hoard MCP server with Codex, removing the old registration first rather than adding a second entry. The page’s Option B: do it yourself section shows the same steps as manual commands with your current key filled in. Two things to know about the installer after a rotation:
  • Rotating your key immediately invalidates every install command you copied before the rotation — the link inside it is bound to the old key and returns an error. Reload the install page after rotating and copy a fresh command. The same applies to a script you saved to a file earlier: it embeds the old key, so fetch it fresh.
  • If Hoard Desktop is installed, the script reads the key from ~/.config/hoard/agent.env (macOS and Linux) or %APPDATA%\hoard\agent.env (Windows) in preference to the embedded value. Update Desktop first, or the old key gets written back.

​
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 → Assistants.
  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:
  • Check your activity log. A rejected bearer key writes no row there, so look for clients that stopped appearing instead: anything still on the old key gets a 401 from mcp.tryhoard.com and drops out of the log. If a client you expect is missing, it hasn’t been updated yet.
  • 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, set HOARD_API_KEY to the new value there too. Use the manual steps in Step 2 for those environments — the installer command embeds your account’s key and its link expires after an hour, so it isn’t a good fit for CI or machines you don’t own.

​
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 → Profile 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 set HOARD_API_KEY to the new value on each machine using the manual steps in Step 2.