Skip to content
PulsVaultDocs
Get started
Solo ProTeamBusinessEnterprise

Lifecycle & rotation

Rotating a credential without downtime, and the disable → archive → restore path — plus revoke versus delete.

Two lifecycles run side by side: the credential's (issue → rotate → revoke → delete) and the identity's (active → disabled → archived). Keeping them separate is what lets you stop one leaked key without taking a pipeline down, and stop an entire machine without hunting for its keys.

Rotating a key without downtime#

Rotation is an overlap, not a swap:

  1. Issue a new key on the same identity. Give it the same scope and allowlist as the outgoing one.
  2. Deploy it into CI, replacing the old token in your secret store.
  3. Verify — watch Last used on the new key, or its usage drawer, until you see traffic.
  4. Revoke the old key.

Never revoke first. Revocation is immediate and final, and a pipeline mid-run does not get a second chance to read its secrets.

Not every reason to rotate needs a rotation

If the token itself is not suspect, the change you want is probably cheaper. Expiry too close → extend the lifetime. Too much reach → re-scope. Wrong network → change the allowlist. All three leave the token in place; see Re-scope & settings.

Rotate the credential when it may have been exposed, when someone with access to it leaves, or on whatever schedule your policy sets. The 30 / 14 / 3-day expiry warnings exist so the scheduled case is planned work rather than an incident.

Revoke, and then delete#

Revoke stops a credential immediately and permanently. There is no un-revoke: a credential that can come back is one you can never confidently say was stopped.

Delete removes the key's record from the list. It is a separate, later act:

Revoke Delete
Effect the credential stops working the row disappears
Reversible no no
Allowed when the key is active the key is revoked and past its retention window
A revoked key's record is retained for 30 days

The moment you most want the record is the moment you are least likely to be thinking about record-keeping: someone revokes a key because it leaked, tidies the list in the same sitting, and the investigation starts the following week against a credential that no longer exists. Audit rows survive, but they name the key by an identifier nobody can resolve to a prefix, an owner or a description. The key grants nothing meanwhile — waiting costs you a row in a list.

The console tells you the date the record becomes deletable rather than greying the button out with no explanation.

Disabling an identity#

Disable is the break-glass switch: every key of that identity is refused immediately, and every pipeline using them fails until you re-enable it. Re-enabling restores them — nothing was revoked, so nothing has to be re-issued.

Use it when you need a machine stopped now and you do not yet know which credential is the problem.

Archiving, and what restore actually does#

Archive retires an identity permanently. It is only reachable from Disabled, and that ordering is the design:

  • Disabling first makes CI go red, which is how you find out what still depended on this machine — while the change is still trivially reversible.
  • Archiving then revokes every remaining key, in one recorded action, and the identity leaves the main list.

Its permissions and full history are retained; archived identities remain visible via the ledger and by including them in the list.

Restore brings an archived identity back as Disabled, never as Active:

Revoked keys are never reinstated

An identity that came back Active with zero working keys would look healthy and serve nothing — "restored, and my pipeline still fails" — so restore lands somewhere that says what is true. Issue new credentials, then re-enable.

Deleting an identity#

There is no delete for a machine identity. Archive is the terminal state, and it is deliberately not destructive: the record of what a machine could reach, and what it did, outlives the machine. If the name is in the way, rename it — a rename is audited and keeps the history attached.

Quick reference#

You want to Do this Reversible
Stop one credential Revoke the key no
Stop a machine right now Disable the identity yes
Retire a machine for good Disable, then Archive restore → Disabled
Replace a token with no downtime Issue → deploy → verify → revoke n/a
Give a key longer to live Settings → lifetime yes
Give a key less reach Re-scope yes
Was this page helpful?