Skip to main content

Rotate a Vault secret without downtime

Phase 6 slice 3 introduced declaragent secrets rotate, which bumps a secret's version and triggers a graceful re-resolve across every active session.

The flow​

  1. Rotate the underlying secret in Vault (out-of-band).
  2. Tell Declaragent to pick up the new version: 
    declaragent secrets rotate secret:slack/bot-token --reason "90-day schedule"
  3. Verify with declaragent secrets describe secret:slack/bot-token — the version field should bump and lastRotatedAt should be fresh.

What happens inside​

  • The secrets resolver invalidates its cache for the ref.
  • Every session that resolved the secret gets a secret_rotated event on its bus.
  • Channel adapters rebind their clients against the new credential on the next inbound / outbound call.
  • The rotation is written to the audit log with the supplied --reason.

Tenant scope​

If you run multiple tenants, scope the rotation:

declaragent secrets rotate secret:slack/bot-token --tenant acme-prod

Rotations without --tenant apply to every tenant that references the same ref.

Failure modes​

SymptomCauseFix
EPERMVault token lacks update on the path.Refresh the Declaragent service principal's Vault policy.
Session sees stale value after rotateCache TTL hasn't elapsed + the session missed the event.declaragent secrets describe — if Declaragent sees the new version, restart the affected session manually.
secret-rotation-overdue alert firesSLO says rotate every N days; you haven't.See runbook.

[placeholder — landing 2026-Q2] Full example with a fake Vault behind packages/core/src/secrets/providers/vault.ts.