Keyfactor ACME API

The Keyfactor ACME server includes a key management APIClosed An API is 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. to allow external account binding information (the EAB Key ID and the EAB HMAC Key) to be generated for claims. This allows you to create claims (see The Claims Command) and associated external account bindings (EABs) to allow ACME clients (e.g. Certbot) to use separate user accounts for each instance of the ACME client. The Key Management API can also be used to rotate EAB keys to renew them.

Table 14: Keyfactor ACME API Endpoints

Endpoint Method Description Link
/KeyManagement GET Returns the external account binding (EAB) key for the user and generates a new EAB key for authorized users without a pre-existing key. GET KeyManagement
/KeyManagement POST Renews the user’s external account binding (EAB) key. POST KeyManagement
/Admin/Accounts/List GET Returns all accounts registered with the Keyfactor ACME server. GET Admin Accounts List
/Admin/Accounts/Revoke POST Revokes the account that has been registered from an account that has been registered from an ACME client. POST Admin Accounts Revoke
Endpoint Common Features

By default, all Keyfactor ACME API methods start with a base path, which corresponds to an application under IIS; this path is configurable at install time. The default base path is ACME. The API component name and method name then comprise the parts of the URL, each separated by a forward slash. For example, /ACME/KeyManagement would be the URL format for the key management methods.

The Keyfactor ACME API uses the following common request headers:

  • Content-Type: application/json

  • Authorization: Bearer <your OAuth token>

HTTP Statuses

The following HTTP Statuses may be returned by Keyfactor ACME API requests:

  • 200 OK: Request successful; results in response body.

  • 400 Bad Request: Malformed or invalid data; additional information may be available in the response body and/or Keyfactor ACME server logs.

  • 401 Unauthorized: Invalid credentials (user unauthenticated).

  • 403 Forbidden: Can often indicate that the user does not have the appropriate permissions for this action in Keyfactor ACME (user unauthorized).

  • 404 Page not Found: Invalid request path.

  • 405 Method Not Allowed: Invalid request; check the requested method (POST vs GET), the authentication credentials, and the endpointClosed An endpoint is a URL that enables the API to gain access to resources on a server. path.

  • 500 Internal Server Error: Keyfactor ACME encountered an unexpected error attempting to handle the request. See response body and Keyfactor ACME server logs for details.

  • 502 Bad Gateway: Keyfactor ACME attempted to contact Keyfactor Command or other upstream server to process the request, but was unable to. See Keyfactor ACME server logs for details.