Secret Versioning

Every change to a secret is tracked as a new version (v1, v2, v3...). You can view the full history of any secret and roll back to a previous version at any time.

How It Works

• When a secret is created, it gets version v1
• When a secret is updated (via dashboard, API, or CLI push), the version increments (v2, v3, etc.)
• When a secret is rolled back, a new version is created with the restored value (non-destructive)

Each version records:

• The encrypted value snapshot
• Who made the change
• The type of change (created, updated, rolled_back)
• A timestamp

Viewing Version History

Dashboard

Click on any secret in the table view to see its details. The Version History tab shows a timeline of all changes.

CLI

envshed versions DATABASE_URL

Options:

Flag	Description
-o, --org <slug>	Organization slug
-p, --project <slug>	Project slug
-e, --env <slug>	Environment slug
--limit <n>	Maximum number of versions to show (default: 20)

API

curl https://app.envshed.com/api/v1/versions/my-org/my-project/production/DATABASE_URL \
  -H "Authorization: Bearer $ENVSHED_TOKEN"

Response:

{
  "versions": [
    {
      "version": 3,
      "changeType": "updated",
      "changedBy": "user-uuid",
      "comment": null,
      "createdAt": "2026-02-19T12:00:00Z"
    },
    {
      "version": 2,
      "changeType": "updated",
      "changedBy": "user-uuid",
      "comment": null,
      "createdAt": "2026-02-18T10:00:00Z"
    },
    {
      "version": 1,
      "changeType": "created",
      "changedBy": "user-uuid",
      "comment": "Initial database URL",
      "createdAt": "2026-02-17T09:00:00Z"
    }
  ]
}

Rolling Back

Rolling back restores a secret to the value it had at a previous version. This creates a new version rather than deleting history, so the rollback itself is tracked.

CLI

envshed rollback DATABASE_URL --version 2

Options:

Flag	Description
--version <n>	(Required) Target version number to roll back to
-o, --org <slug>	Organization slug
-p, --project <slug>	Project slug
-e, --env <slug>	Environment slug

API

curl -X POST https://app.envshed.com/api/v1/versions/my-org/my-project/production/DATABASE_URL/rollback \
  -H "Authorization: Bearer $ENVSHED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"targetVersion": 2}'

Important Notes

• Rolling back is non-destructive — it creates a new version with the old value
• Version history is retained even if a secret is deleted (via ON DELETE CASCADE on the versions table)
• All version operations are recorded in the audit log
• Secret values in version history are encrypted with the same AES-256-GCM encryption as current values