Secret version

A secret version is a numbered copy of a secret value stored under one secret container. It lets teams rotate credentials without changing the secret name, while preserving auditability and rollback options. In practice, version management becomes a governance task because old versions can remain active, billable, and reachable until they are disabled or destroyed.

Expanded Definition

secret versioning is the control layer that tracks each change to a secret value while keeping the secret’s container stable. In NHI operations, that matters because applications, service accounts, and automation pipelines often reference a secret by name, while the platform serves a specific version behind the scenes. This lets teams rotate API keys, tokens, and certificates without rewriting every consumer at once, and it preserves audit trails for who changed what, when, and why.

Definitions vary across vendors on whether a version is merely metadata or a separately addressable credential state, so implementation details should be read carefully. The operational distinction is important: versioning is not the same as rotation, and it is not the same as revocation. A new version may exist while older versions remain usable until they are disabled, expired, or destroyed. That is why version control belongs in governance, not just in storage mechanics.

For broader NHI context, the Ultimate Guide to NHIs — Static vs Dynamic Secrets explains why secret lifecycle choices shape exposure, while the OWASP Non-Human Identity Top 10 treats secret handling as a core risk area. The most common misapplication is assuming a rotated secret is safe simply because a new version exists, which occurs when older versions remain enabled for legacy jobs or delayed cutovers.

Examples and Use Cases

Implementing secret versioning rigorously often introduces migration overhead, requiring organisations to weigh rotation speed against application compatibility and rollout risk.

• A CI/CD system reads the current version of a deployment token while a newer version is staged, tested, and promoted after validation.
• A cloud service maintains multiple certificate versions so that clients can trust the new credential while old nodes drain gracefully.
• A security team audits version history to identify whether a compromised secret was merely rotated or actually disabled and destroyed.
• During an incident, a platform operator rolls back to a prior version to restore availability, then forces re-rotation after the root cause is contained.
• Version metadata supports investigations into supply chain events such as the Reviewdog GitHub Action supply chain attack, where exposed secrets must be traced across histories and consumers.

Industry guidance is still evolving on how long older versions should remain recoverable, especially in distributed systems where rollback and blast-radius reduction conflict. The NHI Management Group research on Guide to the Secret Sprawl Challenge shows why versioned secrets still become sprawl when stale copies are not retired. For lifecycle terminology, the NIST SP 800-63 Digital Identity Guidelines remain useful as a reference point for assurance thinking, even though they are not written specifically for secrets versioning.

Why It Matters in NHI Security

Secret versioning becomes a security issue when teams confuse “new version” with “no remaining exposure.” Old versions can stay active in caches, replicas, pipeline variables, and third-party integrations, creating a hidden attack path after rotation. That is especially dangerous in NHI environments, where credentials are often embedded in automation and reused across services with limited human visibility. NHIMG data shows that 71% of NHIs are not rotated within recommended time frames, and 96% of organisations store secrets outside of secrets managers in vulnerable locations, which means version drift often compounds with secret sprawl.

The governance question is not only whether the current version is strong, but whether previous versions are disabled, destroyed, and fully accounted for across every consumer. This is where 52 NHI Breaches Analysis and the 230M AWS environment compromise illustrate the same pattern: a credential event is rarely contained by creation of a replacement alone. Organisations typically encounter the consequence only after a leak, lateral movement, or failed cutover, at which point secret version control becomes operationally unavoidable to address.

Related resources from NHI Mgmt Group

• Idle Secret
• What is the difference between an identity, a credential, and a secret?
• Why is proactive secret scanning important for NHI security?
• What is the difference between privilege reduction and secret rotation?