Rotating API keys when an agent has seen them: a practical playbook

Most teams have a rotation process for the classic leak: a key pushed to GitHub, pasted in a chat, or left in a log file. But there is a leak path that rarely triggers that process: a key that an AI coding agent has seen. It did not go to GitHub. It went into the agent’s context window, and from there into session transcripts, project summaries, log files, and the request logs of whatever model provider processed that context. For practical purposes, that key is public. The rotation process should treat it that way.

Step 1: Detect exposure

You need a record of what the agent touched. Three sources, in order of reliability:

• An audit log of credential access. If credentials flow through a broker, it can tell you exactly which keys were resolved, when, and by which invocation. This turns “did the agent see it?” into a lookup.
• Session transcripts. Agent sessions persist locally; grep them for key prefixes if you suspect a specific value.
• Config and env scans. Keys stored in settings.json, opencode.json, or .env were visible to every session, not just one.

Step 2: Revoke first, replace second

The order matters. Create the new key after revoking the old one, and revoke with immediate effect rather than a grace period. The window between “old key still valid” and “new key deployed” is when a leaked value is usable, so keep it as short as possible. Provider dashboards support immediate revocation; the only reason to delay is long-running jobs that cannot restart.

Step 3: Create a scoped replacement

The replacement should be narrower than the original: one key per service, minimal permissions, and an expiry if the provider supports it. If the new key keeps the old broad scope, you have only reset the clock.

Step 4: Update the store, not the files

This is where a credential broker pays for itself. With pass or Bitwarden as the single source of truth, rotation is one edit to one entry — the next trustless run -s KEY -- <cmd> injection picks up the new value automatically. Without a store, you are hunting through N config files, MCP server env blocks, CI variables, and teammates’ machines, hoping you found them all.

Step 5: Verify from a clean environment

After rotating, confirm from a fresh shell (not the agent’s session, which may hold cached state):

• The old key fails authentication.
• The new key succeeds.
• The agent can still complete its normal workflow with the new value.

If the agent cached the old key in session state, discard that session — otherwise it keeps retrying a dead credential.

Step 6: Sweep downstream

Keys have a habit of replicating. Check CI secret stores, dashboards, backups, MCP server configs, and any document that recorded the old value. For OAuth credentials, treat the token as dead once the refresh token has been used: single-use rotation means a stale refresh is never retried — a reauth_required status means the session is over and a new device flow is the only way forward.

The part people skip

Revoking is easy. The hard part is knowing the full inventory of what the agent touched, which is exactly what an append-only audit log gives you. A broker that logs every key resolution makes step 1 a query instead of a forensic investigation — rotation becomes routine.

trustless keeps that audit trail and injects rotated values from your existing store, with OAuth device-flow handling built in. The command reference is at /docs/commands/.

When was the last time you rotated a key that an agent had seen — and how long did the inventory take?