Skip to main content
Version: latest

API Versioning and Deprecation

VaultPAM uses path-major versioning for public HTTP APIs.

Versioning model​

  • Additive changes stay in the current major version.
  • Breaking changes require a new major path such as /api/v2/.
  • The current public major is v1.

Breaking changes​

A change is breaking when it removes or narrows an existing client contract, such as:

  • removing an endpoint or HTTP method,
  • making an optional request field required,
  • removing a response field that existing clients use,
  • changing a field type in an incompatible way,
  • tightening auth or access rules in a way that breaks documented clients.

Deprecation and sunset​

  • Deprecated operations are marked in the API contract.
  • Release notes include migration guidance in the same release that introduces the deprecation.
  • Deprecated behavior stays available for at least two tagged production releases before removal.
  • Sunset dates are announced in advance so customers can plan their migration.

Migration support​

When an API changes, the replacement path should be documented alongside the deprecation notice. Customers should not need to guess which endpoint or payload shape to move to next.

Need help?​

Use the live API reference for current endpoint details and the release notes for changes that affect upgrades.