POST Alerts Key Rotation Test

The POST /Alerts/KeyRotation/Test method is used to test a specific SSHClosed The SSH (secure shell) protocol provides for secure connections between computers. It provides several options for authentication, including public key, and protects the communications with strong encryption. key rotation alert. This method returns HTTP 200 OK on a success with details about the SSH key rotation alert or a response of “NoActionTaken” if no keys match the test criteria entered.

Tip:  Alerts are generated when an SSH key is approaching or has reached its stale date as defined by the timeframe configured in the alert and the SSH key lifetime (the Key Lifetime (days) application setting).

By default, a maximum of 100 alerts will be generated during a test. The maximum value is configurable with the Key Rotation Alert Test Result Limit setting in Keyfactor Command application settings (see Application Settings: Console Tab). If more than 100 alerts are generated, no email messages will be sent and you'll have the opportunity to view the first 100 alerts generated.

If you're using an event handler, the event handler is run and the handler actions taken (PowerShell script run, event log message written) when the test is run. This is true regardless of the setting of the SendAlerts flag.

Tip:  The following permissions (see Security Roles and Claims) are required to use this feature:

/monitoring/alerts/read/
/monitoring/alerts/test/

Table 193: POST Alerts Key Rotation Test Input Parameters

Parameter

In

 Description
AlertId Body

Required. An integer of the reference ID of the SSH key rotation alert to test.

Use the GET /Alerts/KeyRotation method (see GET Alerts Key Rotation) to retrieve a list of all your key rotation alerts to determine the alert Id.
EvaluationDate Body

Required. A string indicating the start date/time for the test. The date and time should be given using the ISO 8601 UTC time format YYYY-MM-DDTHH:mm:ss.000Z (e.g. 2023-11-19T16:23:01Z).

You can use the date range to simulate running the alerts a month from now instead of today, for example, or put in a broad date range to be sure you pick up some expiring keys for testing purposes.
PreviousEvaluationDate Body Required. A string indicating the end date/time for the test. The date and time should be given using the ISO 8601 UTC time format YYYY-MM-DDTHH:mm:ss.000Z (e.g. 2023-11-19T16:23:01Z).
SendAlerts Body A Boolean indicating whether to send alert emails with the test (true) or not (false). The default is false.

Table 194: POST Alerts Key Rotation Test Response Data

Parameter Description
KeyRotationAlerts

An object containing alert details resulting from the test. ClosedShow expiration alert details.
AlertBuildResult A string indicating the outcome of the test (e.g. Success).
Tip:  See the Keyfactor API Reference and Utility which provides a utility through which 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. endpoints can be called and results returned. It is intended to be used primarily for validation, testing and workflowClosed A workflow is a series of steps necessary to complete a process. In the context of Keyfactor Command, it refers to the workflow builder, which allows you automate event-driven tasks when a certificate is requested or revoked. development. It also serves secondarily as documentation for the API. The link to the Keyfactor API Reference and Utility is in the dropdown from the help icon () at the top of the Management Portal page next to the Log Out button.