Version management

Secret version management

Each secret value is a numbered version. This page covers version lifecycle, destroying individual versions, and deleting entire secrets.

Version lifecycle

Create secret → version 1 (current)
    │
    ├─ putSecretValue → version 2 (current), version 1 (readable)
    │
    ├─ putSecretValue → version 3 (current), versions 1–2 (readable)
    │
    ├─ getSecretValue → read current or any readable version
    │
    ├─ destroySecretVersion → version N marked destroyed (unreadable)
    │
    └─ deleteSecret → all versions removed, path available for reuse

Current version

The latest active version is marked with stage current. When you call getSecretValue without specifying a version, the current version is returned.

Each putSecretValue increments currentVersion and advances the current stage to the new revision.

Version history

Retrieve version history without values:

GET /v1/secrets/{region}/secret/app/production/db/password?includeVersions=true

The response includes per-version metadata:

Field	Description
`version`	Version number
`status`	`active` or `destroyed`
`stage`	`current` for the latest active version
`valueFormat`	`string` or `keyValue`
`createdAt`	Creation timestamp
`lastAccessedAt`	Last successful reveal timestamp

Destroyed versions remain in history for audit purposes but cannot be decrypted.

Destroy a version

Mark a specific version as destroyed:

DELETE /v1/secrets/{region}/secret/app/production/db/password/versions?version=2

After destruction:

The version value cannot be read again
Other versions and the secret container are unaffected
The version remains in history with status destroyed
Billing for that version stops

Requires delete permission on the path.

When to destroy versions

After rotating a secret:

Add the new version with putSecretValue
Confirm all consumers use the new value
Destroy superseded versions to limit exposure and reduce version storage billing

Do not destroy the current version while applications still depend on it.

Delete a secret

Delete the entire secret and all its versions:

DELETE /v1/secrets/{region}/secret/app/production/db/password

This is a soft delete from the customer’s perspective:

The secret and all versions are removed
The path becomes available for reuse
There is no cancel-deletion or recovery API

Treat delete as permanent. Requires delete permission on the path.

Before deleting a secret, confirm no applications, CI pipelines, or integrations still reference the path.

KMS key lifecycle interaction

KMS key state	Metadata APIs	`getSecretValue` / `putSecretValue`
`active`	✓	✓
`disabled`	✓	✗ (`400`)
`pending_deletion`	✓	✗ (`400`)

Disabling or deleting a KMS key breaks secret value operations for secrets bound to that key. Metadata remains readable. See KMS integration.

Billing impact

Action	Billing effect
Create secret	Version 1 is billable
`putSecretValue`	New version is billable
`destroySecretVersion`	Billing stops for that version
`deleteSecret`	Billing stops for all versions

See Billing for metering details.