How to Rotate Credentials an Agent Can Reach

Quick answer
Start with the inventory: every credential in the agent’s environment, workspace, and tool configuration.
Prefer short-lived credentials issued per run over long-lived keys that someone must remember to rotate.
Rotate on a schedule for standing credentials, and immediately when a run behaves unexpectedly or a transcript may have leaked.
Verify the old credential is actually rejected before declaring the rotation complete.
Automate the rotation, because a manual checklist fails exactly when things are busy.

What needs to be in the inventory?

Environment variables, .env files in the workspace, tool configuration for MCP servers, cloud credential files, SSH keys, browser sessions, and anything in a global config the harness reads. Also include credentials the agent can obtain at runtime, such as a cloud metadata token.

For each one, record what it can do, who owns it, where it is stored, and how it is rotated. A credential without an owner is the one that stays valid for three years after the person who created it left.

# Find credentials in the agent's reach
env | grep -iE 'token|key|secret|password' | cut -d= -f1
grep -RInE 'token|api_key|secret' .agent .mcp.json 2>/dev/null | head -20
ls -la ~/.aws ~/.config/gh ~/.ssh 2>/dev/null

How do you move from long-lived to short-lived?

Issue credentials to the run from a trusted service: workload identity, a token broker, or a secrets manager that authenticates the run. The agent never sees a permanent key, and the credential expires even if nobody rotates it.

For third-party APIs that only support static keys, put the key behind a proxy. The agent calls the proxy, the proxy holds the key, and rotation becomes a proxy configuration change rather than a workspace change.

When should you rotate immediately?

After any run that behaved unexpectedly, after a skill or MCP server was installed, after a transcript may have included a secret, and after any credential appeared in a commit or a log. Rotation is cheap; deciding whether an exposure was real is not.

Also rotate when someone leaves, when a shared credential changes hands, and when a provider reports an incident involving the service. Those are events outside your system that still affect your exposure.

How do you confirm the rotation worked?

Test that the old credential fails. A rotation that issues a new key but leaves the old one valid is a false sense of safety, and it happens when the old secret exists in more places than the inventory recorded.

Then check what else used it. A credential shared between the agent and a cron job will break the cron job when rotated, and that is better discovered in a test than at 3am. After rotation, update the inventory and the automation together.

Where this bites vibecoders
The agent usually inherits the developer’s entire credential set: cloud config, GitHub login, SSH keys, and a .env with production values. Rotating one token after an incident does nothing if the other paths are still open. Inventory first, then shrink, then rotate.

Where AI coding assistants get this wrong

Rotating one key while other long-lived credentials remain reachable.
Issuing a new key without revoking the old one.
Keeping rotation in a manual runbook nobody runs.
Forgetting credentials reachable through cloud metadata.
Rotating without checking which automations shared the key.
Storing the new key in the same workspace the agent can read.

Checklist

Inventory every credential the agent can reach.
Record owner, scope, storage, and rotation method.
Move standing keys to short-lived or proxied credentials.
Rotate after any suspicious run or exposure.
Verify the old credential is rejected.
Automate rotation and update the inventory.

FAQ

How often should I rotate?

Short-lived credentials rotate automatically, which is the goal. For standing keys, rotate on a fixed schedule and on every suspicion event. The schedule matters less than the ability to rotate quickly and verify that the old one is dead.

Does rotation break running agents?

It can, which is why the credential should be issued to the run rather than shared. A run that holds a credential for its duration is fine; a run that reads a shared key at an arbitrary moment will fail when the key changes.

What about keys in CI secrets?

Treat them as standing credentials with a rotation schedule, and prefer OIDC federation to long-lived secrets where the platform supports it. A CI secret that never rotates is a permanent key stored in a system many people can read.

How do I know a secret was exposed?

You cannot know for certain. Treat any read of a secret into model context as exposure, and rotate. The absence of evidence in the repository does not prove the secret stayed on the machine.