> ## 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.

# Rotating your agent bearer key

> How to revoke and reissue your Hoard bearer key without breaking your Codex CLI install. When to rotate, what gets affected, and the one-line reinstall.

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:

```bash theme={null}
curl -fsSL https://www.tryhoard.com/install/codex.sh | bash
```

On Windows, in PowerShell:

```powershell theme={null}
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:

   ```bash theme={null}
   codex mcp add hoard \
     --url https://mcp.tryhoard.com/mcp \
     --bearer-token-env-var HOARD_API_KEY
   ```

### 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](https://www.tryhoard.com/settings/connected-apps).
2. Click **Revoke** next to Claude and ChatGPT.
3. Reconnect each one from their respective setup pages: [Claude](/connect-to-claude), [ChatGPT](/connect-to-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](/tutorials/reading-the-audit-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.

## Related reading

* [Connect Hoard to OpenAI Codex](/connect-to-codex), full Codex setup
* [Agent permissions and safety](/agent-permissions), what the bearer key gates against
* [Reading your agent activity log](/tutorials/reading-the-audit-log), verify the rotation worked
* [When the agent says 'I can't do that'](/tutorials/when-the-agent-says-no), diagnose post-rotation auth errors