Skip to main content

Get Secret

Returns metadata for a single secret. The encrypted value is not included.

Path Parameters

Response

The environments array

One entry per environment that holds a value, ordered by environment name.

Detecting a rotation you did not perform

value_version is the only field here that means “the stored value changed”. It increments only for writes that replace the value:
  • PUT /v1/secrets/:id/value
  • value and certificate updates made in the KnoxCall dashboard
  • platform-managed custodial key rotation
  • importing over an existing environment during a secret-store migration
It deliberately does not increment for writes that leave the value intact:
  • OAuth2 token refreshes (the token churns; the client secret does not)
  • per-environment expiry overrides
  • certificate metadata re-parsing and mTLS binding changes
  • renaming an environment
  • BYOK rewrap — the same plaintext re-encrypted under a new tenant key
All of those move updated_at, which is why updated_at cannot be used as a rotation signal, and a BYOK rewrap changes the stored checksum, which is why that cannot either. Store the value_version returned by your own PUT /v1/secrets/:id/value call and compare it with the one here. A higher number means someone rotated the secret outside your tooling. Creating an environment’s first value produces version 1, not 2 — creation is not a rotation.

Errors