Credential rotation is not swapping a key in a vault. Done properly, AI agent credential rotation means expiring a grant, revoking the old credential, reissuing least-privilege access under a new bounded plan, and proving every step in the audit log. Done casually, it means a new secret pasted into the same unbounded setup that made the old one dangerous — and the old one, very often, still working.
Stale credentials are production permissions nobody has reviewed. Builders on Hacker News have put the underlying question plainly: who can use which agent, and what can each agent access? A credential answers the second half of that question in practice. If you cannot say which identity holds it, which grant issued it, and when it expires, you do not have a credential under management. You have a standing permission with no owner. This checklist turns rotation into nine checkable controls, drawn from the Governed Agent Mesh Playbook.
The AI agent credential rotation checklist
- Inventory every credential by identity, not by service. Every agent, script, cron job, and scheduled workflow that can take an action holds a stable, owner-scoped identity in the format
agent:[OWNER]/[NAME], recorded in an identity registry with the identity, its owner, the date issued, and its status. Build the rotation list from that registry: for each identity, list every credential it holds, the capability each one unlocks, and the grant that authorised it. Anonymous, shared, or unregistered actors are rejected at the dispatch path — never warned about — so a credential that cannot be tied to a recorded identity is not a rotation candidate. It is a finding, and it is revoked, not rotated. - Tie every credential to an expiring grant. Grants are records, not assumptions. Every grant records its capability, its scope, the issuing owner, the date issued, an expiry date, and the identity it is issued to. The credential is the grant made usable: it lives and dies with that record. Permanent grants are prohibited, and auto-grant is prohibited — every grant requires an explicit issuance decision. If a credential in your stack has no expiry, rotation is not a schedule you add later; the missing expiry is the defect, and the fix is a new grant with an end date, not a new secret under the old terms.
- Schedule rotation before expiry, not after an incident. Rotation planned around the grant's expiry date is routine maintenance. Rotation improvised after an incident is a permission change made under pressure, by whoever is awake, with the audit trail written afterwards if it is written at all. Work from the registry: when a grant approaches expiry, the rotation is prepared — new grant drafted at least-privilege scope, approval recorded, new plan validated — before the old one lapses. An agent whose grant expires mid-workload is not failed by the calendar. It is blocked, correctly, because the evidence that it may act has run out.
- Reissue at least privilege, every time. Rotation is the cheapest moment to shrink scope, because you are reissuing anyway. Shrink each new grant to the minimum capability and scope the agent has demonstrated it needs — list capabilities the way agents actually invoke them, as tool names, API calls, and cron jobs, not the way an architecture diagram describes them. Capabilities the agent once used and no longer calls come off the grant. A rotation that reissues the old scope unchanged has refreshed a secret and preserved the risk: the credential is new, the permission is exactly as broad as it was on the day nobody reviewed it.
- Hard-gate any rotation that changes scope. Accessing, reading, or transmitting credentials and changing agent permissions are Hard-gated actions in the Playbook: they always require a recorded human approval, with no auto-grant path, ever. A like-for-like rotation inside an existing grant follows the recorded process. A rotation that widens a capability, broadens a scope, or extends an expiry beyond policy is a permission change, and it waits for a human holding the approver role. The acting agent can never approve its own action. Each approval is recorded with the approver's identity, the timestamp, the action reference, and the decision — and a denied approval persists as an exact blocked result, never a silent skip.
- Revoke the old credential, and state the overlap rule. A rotation is not complete while the old credential still works. Revoke it as part of the same recorded action that issues the replacement, or — where a workload genuinely cannot restart instantly — state a short, bounded overlap in the new plan, with its end written down, and revoke at that end without exception. Plans are immutable once execution starts, so an overlap is a bound of the new plan, not a favour the old credential keeps. The parallel rule for identities is absolute: decommissioned agents have their identities revoked, and a revoked identity is never reissued to a different agent.
- Keep secret values out of plans, logs, and audit rows. A plan bound references the grants it relies on; it does not carry credential values. Audit rows record the actor, the action, the target, the outcome, and the timestamp — the target is the grant or credential reference, never the secret itself. Audit data never contains secrets or credentials; that material lives outside the log. This matters most during rotation, when values are being handled directly: the row proves that a named identity rotated a named grant at a stated time and a human approved it. The value itself is evidence of nothing except exposure.
- Test the negative cases before you close the rotation. After reissue, attempt the failures on purpose. The old credential must fail. A request under the expired grant must be blocked and recorded. A request with no recorded identity must be rejected at the dispatch path. When required evidence is missing — identity, grant, approval, budget headroom — the action fails closed: it is blocked, recorded as blocked, and never retried automatically, because a retry requires new evidence, not a timer. A rotation whose old key quietly still works has not rotated anything; it has doubled the number of live credentials for the same permission.
- Record every step, then review on a cadence. Every request, approval, block, and outcome in the rotation writes an audit row, hash-linked to the row before it: sequence and chain are what turn a list of events into evidence a reviewer can recompute. Early deletion or modification of rows requires approval and is itself recorded as an audit row, and any synthetic or demo rows are labelled “synthetic demo”, never mixed silently into real telemetry. Then keep the registry honest over time: expiries approaching, grants unused, identities with no recent action — each is a review item with a named owner, worked before it becomes an incident item.
What breaks without rotation
Each skipped control fails quietly. Without an identity inventory, the first credential you learn about is the one an incident names. Without expiries, yesterday's temporary access becomes permanent by default, because nothing in the system ever asks whether it is still needed. Without revocation, every rotation adds a live credential instead of replacing one. Without the audit rows, none of it is reconstructable afterwards: you would have secrets in production with no record of who issued them, who approved them, or when they were supposed to end. And governance failures compound with the ordinary failures of unbounded agents — the runaway loop that cost one developer $700 in 72 hours was not missing a dashboard; it was missing bounds that stopped it. Credentials are a bound of exactly the same kind.
Before you call it rotated
Rotated does not mean a new value exists. It means the old credential fails, the new one is tied to a complete grant record — capability, scope, issuing owner, date issued, expiry, identity — at least-privilege scope, any scope change carries a recorded human approval, no secret value appears in any plan or audit row, and every step, including every block, is a hash-linked audit row a reviewer can verify. If any one of those cannot be shown, the rotation is a claim, not a control.
Put this into practice
Rotation is one maintenance loop inside a larger discipline. The Governed Agent Mesh Playbook — Studio Edition (https://ghostcorpnet.gumroad.com/l/hdigmr) gives you the working documents behind this checklist: the six adopt-as-is policies covering identity, grant issuance, hard-gated actions, spend limits and expiry, fail-closed blocks, and audit-row retention, the plan-bound and audit-row schemas those grants and rows validate against, the risk-tier worksheet, and the 14-day rollout that installs them in order. Adopt the grant record once — then rotation stops being an emergency procedure and becomes a date on a registry.