Versioning

The Keyfactor Web APIs are versioned as a set and released in conjunction with Keyfactor Command at the same version level (e.g. version 10.3). In addition, both the Keyfactor APIClosed A set of functions to allow creation of applications. Keyfactor offers the Keyfactor API, which allows third-party software to integrate with the advanced certificate enrollment and management features of Keyfactor Command. and the Classic API1 have multiple versions of select endpoints.

The current strategy is to increment the version of an API when changes are made that might break backwards compatibility for existing clients. New endpoints are generally implemented in the most recent version of their API.

Generally, updates to an existing version of an endpointClosed An endpoint is a URL that enables the API to gain access to resources on a server. are restricted to updates that should not break existing clients. Updates may be made that add HTTP response headers or response body parameters, or that correct existing bugs, or must be made to conform to newer or more granular security constraints. When an update cannot be made without breaking existing clients, a new endpoint is added in a later API version.

The Classic API provides various methods to retrieve the version of Keyfactor Command. For example, values for both the Classic API version and the Keyfactor Command version are returned in HTTP headers with each response to an API call. Additionally, the Status endpoint (see Status) provides additional information about the capabilities of the Classic API in its installed version. The Keyfactor API does not presently have an equivalent functionality.

Most Keyfactor API endpoints have only one version, though a second version has been released for a select few endpoints. The Keyfactor API uses the x-keyfactor-api-version request header to differentiate between versions 1 and 2 of a given endpoint. If a version isn't specified, version 1 is assumed.

Several endpoints of the Classic API have their own incremental versioning. For example, the CertEnroll endpoint has three versions, the most recent of which is three:

  • CertEnroll/1
  • CertEnroll/2
  • CertEnroll/3

As the Keyfactor Web APIs have evolved and continue to evolve, an additional security constraint is available to limit access to deprecated legacy versions of API endpoints. In many cases, newer versions of an endpoint are more secure and robust, easier to use, and offer more functionality. Keyfactor highly recommends use of the newest endpoints wherever possible. To this end, it is possible to disable deprecated API endpoints in the Classic API from the API Application Settings within the Keyfactor Command Management Portal. In Keyfactor Command 10.3, this setting will disable the following endpoints:

If the Allow Deprecated API Calls setting is disabled, any client attempting to access one of these endpoints will receive an error message instead of the expected results. This will, of course, prevent client applications that rely on these endpoints from functioning, and if these applications cannot be updated to the newer endpoints then the Allow Deprecate API Calls setting must be enabled. Otherwise, Keyfactor recommends that these endpoints be disabled to reduce exposure to unauthorized or unintended use.

The following endpoints have been removed from the Classic API and are no longer supported:

  • CertEnroll/1/Templates
Note:  API versioning strategy in Keyfactor Command shifted somewhat between versions 4.0 and 5.0 (when the product was known as Certificate Management System or CMS). As such, the API versioning mechanisms described in CMS 4.0-4.5 documentation, while still generally correct, are no longer our primary recommendation.