Key Rotation

How it works

Key rotation runs a credential through a short, repeating lifecycle instead of minting one secret and trusting it forever. The loop is deliberate:

1. Issue a new key with a defined expiry and the narrowest scope the caller needs.
2. Overlap the new and old keys for a grace window so live callers migrate without a hard cutover.
3. Cut over every consumer to the new key and confirm it is in use.
4. Revoke the old key on its own schedule — not merely let it expire — so a leaked copy stops working immediately.
5. Audit which identities used which key, so you can trace exposure after the fact.

Two properties make this work. First, rotation is scheduled: the clock forces a fresh secret whether or not you suspect a leak, so a quietly stolen key still dies on its own. Second, revocation is independent: you can kill a specific key at any moment without waiting for the next rotation. Scoping matters as much as timing — a rotated key that still holds broad write access has a short life but a wide reach. The mechanism is only as strong as the smallest scope you can issue against.

Why it matters in an agent harness

An agent harness hands credentials to code that decides its own next move. The agent authenticates to tools, MCP servers, and external APIs; every one of those secrets can end up in a prompt, a log line, a checkpoint, or a captured trajectory. Static keys turn each of those surfaces into a permanent liability. Rotation converts a permanent liability into a bounded one: a key that leaks into a trace is dangerous for hours, not indefinitely.

Rotation also gives you a containment lever that pairs with the rest of the harness. When a run goes wrong — a prompt-injection payload steers a tool call, a subagent escalates beyond its scope — independent revocation lets you sever that agent's access without tearing down the whole system. It is the credential-layer complement to a permission boundary: least privilege limits what a key can do, rotation limits how long it can do it. Observability closes the loop, because per-key audit trails tell you which agent, which run, and which tool touched a compromised secret before you pulled it.

Key rotation vs. revocation

These are easy to conflate and they answer different questions. Rotation is the routine clock; revocation is the emergency stop. You need both, and treating one as a substitute for the other leaves a gap.

Rotation without revocation means a known-bad key survives until its window closes. Revocation without rotation means you only ever act on the leaks you detect, and silent compromises persist. Design the schedule and the kill switch as one system.

The Rifty take

We treat every credential an agent carries as already leaked and design for the blast radius, not the probability. That means we optimize for the shortest lifetime and narrowest scope a workflow can tolerate, and we accept the operational cost of overlap windows and re-issuance to buy independent revocation. The boundary we enforce is simple: no agent holds a long-lived, broadly-scoped key, because a harness you cannot cut off is not a harness.

Implementation checks

• Give every key a hard expiry; no non-expiring secrets in the harness.
• Keep revocation independent of the rotation clock — you must be able to kill one key immediately without waiting for the schedule.
• Overlap old and new keys during cutover, then revoke the old one deliberately rather than letting it drift to expiry.
• Scope keys to the smallest tool surface and read/write access the agent actually uses; a short life does not fix a broad reach.
• Attribute usage per key so an audit can name the agent, run, and tool behind a compromised credential.
• Scan prompts, logs, checkpoints, and stored trajectories for credential material — these are where agent secrets leak.
• Rehearse an emergency rotation before you need one; an untested kill switch is a hope, not a control.

Frequently asked questions

How often should an agent's keys rotate?

Rotate as frequently as your cutover tooling can tolerate without breaking live callers; shorter windows shrink exposure. Base the interval on blast radius, not convenience: a broadly-scoped key servicing many agents deserves aggressive rotation, while a tightly-scoped read-only key can rotate less often. Automate it so the schedule never depends on someone remembering.

Is key rotation the same as revocation?

No. Rotation is the scheduled clock that ages every key out automatically, whether or not you suspect a leak. Revocation is the on-demand kill switch that severs a specific key immediately. You need both: rotation limits how long any key lives, revocation gives you fast containment during an incident. Neither substitutes for the other.

Does rotation replace least privilege for agents?

No — they are complementary controls on different axes. Least privilege limits what a key can do; rotation limits how long it can do it. A rotated key that still holds broad write access has a short life but a wide reach. Scope the key narrowly and rotate it; each control covers the other's gap.

Where do agent credentials actually leak?

Most often into surfaces the harness itself creates: prompts, log lines, saved checkpoints, and captured trajectories that get replayed or shared. Any place an agent's context is persisted or observed can carry a secret. Rotation matters precisely because these surfaces are hard to fully scrub, so you bound the key's usefulness instead.

What breaks if I skip the overlap window during rotation?

A hard cutover with no overlap tends to strand in-flight agent runs and long-lived tool sessions that authenticated with the old key, causing mid-trajectory failures. Issue the new key, let both work during a grace window, migrate every consumer, confirm the switch, then revoke the old key deliberately rather than dropping it instantly.