Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tryhoard.com/llms.txt

Use this file to discover all available pages before exploring further.

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. It takes about 3 minutes.

​
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: Revoke the old key

Open Settings → Assistants → API keys. Find the key in the list and click Revoke. Confirm. The old key is now dead. Any in-flight request using it will return an auth error on its next call. If you want to verify it’s dead, try a hoard.sync.health call from a terminal that has the old key, it should fail.

​
Step 2: Generate a new key

Same page, click Generate new key. Copy the 64-character hex string immediately, Hoard shows it once and never again. If you lose it before pasting it somewhere safe, repeat this step. 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.

​
Step 3: 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: 
curl -fsSL https://www.tryhoard.com/install/codex.sh | bash
On Windows, in PowerShell: 
iwr -useb https://www.tryhoard.com/install/codex.ps1 | iex
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: 
    codex mcp add hoard \
  --url https://mcp.tryhoard.com/mcp \
  --bearer-token-env-var HOARD_API_KEY

​
Step 4: 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 5 (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. Settings → Assistants → 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 generated two keys at different times and you can’t remember which is in your shell. The fix: revoke both and generate a third. Re-run the installer. Now you know. Hoard never exposes the value of an existing key after creation. There is no “show me my current key” button by design, if the dashboard showed it, a screen capture or shoulder surf would leak it.