Renew a Certificate in Async mode

The API initiates a request to renew an existing certificate in asynchronous mode. Upon successful triggering of the renew certificate API, the response includes a resourceId. This resourceId can be utilized to trigger the search API API, retrieving the newly created certificate. Please refer to the After you are done section for steps to approve and implement the request.

Before you begin

Ensure the following before attempting to renew certificate from any CA through AppViewX:

The CA setting should be configured in AppViewX for the CA.
Connectivity to the CA via the chosen setting should be working correctly.
Approval:
- Manual approval must be enforced: To do this, set the autoApproval flag to false. Users can approve specific requests by following the After you are done section.
- Auto-approval of certificate requests must be enabled: This is default behavior; if this attribute is not specified, by default, manual approval is bypassed and auto-approval is enabled.

Request Structure


Endpoint:	/certificate/action
Type:	PUT
Sample URL:	`https://<IP/HostName/TenantName>:<GWPORT>/avxapi/certificate/action?gwsource=external&autoApproval=false` To understand the elements of the sample URL, click here.
Headers
Content-Type:	application/json

Table 1. Input Parameters
Name	Description
sessionId `Header`	(Mandatory) Session ID received after login. Type: String Constraint: Required if username and password are not provided.
username `Header`	(Mandatory if sessionId is not provided) AppViewX login username. Type: String Constraint: Required if sessionId is not provided.
password `Header`	(Mandatory if sessionId is not provided) AppViewX login password. Type: String Constraint: Required if sessionId is not provided.
Content-Type `Header`	(Mandatory) Specifies the nature of the data in the payload. Type: String Constraint: Value of the parameter should be ‘application/json’
gwsource `Query`	(Mandatory) Source from which the request is triggered Type: String
autoApproval `Query`	(Optional) Automatic approval workflow enforcement for processing certificate requests If this parameter is not included in the query, auto-approval is enabled by default. To enforce a manual approval workflow for processing the certificate request, set this parameter to false.
Payload `Body`	Contains all the parameters to be sent in the request body for the put request. Type: Payload

Payload

Table 2. Payload
Name	Description
resourceId	(Optional) Unique Id of the certificate. (The resourceId in the above request can be found through the search API using commonName, serialNumber or other search parameters.) Type: String Constraint: Required if the commonName and serialNumber are not specified.
commonName	(Optional) Common name of the certificate. Type: String Constraint: Required if resourceId is not specified.
serialNumber	(Optional) Serial number of the certificate. Type: String Constraint: Required if resourceId is not specified.
action	(Mandatory) Action name for the renewal. Type: String Constraint: Value should be Renew
challengePassword	(Optional) Base64 encoded value of challenge password Type: String Constraint: Applicable and mandatory for Symantec Certificate Authority.
validityUnit	(Optional) Unit of time for the certificate's validity period Type: String Possible values: years, months, days
validityUnitValue	(Mandatory if validityUnit has been specified) Number of units of the time specified as the validity unit Type: Integer
workflowType	(Optional) To renew the certificate without executing the workflow, set this to direct. By default, the workflow for certificate renewal is executed. Type: String Possible values: direct
forceAction	(Optional) Explicitly specify whether to proceed with Renew or Reissue, overriding the default recommendation for DigiCert certificates. If not specified, AppViewX applies its default recommendation based on the remaining time on the existing CA order. Type: String Possible values: renew, reissue Note: For DigiCert certificates, the renewal process checks the remaining validity of the existing CA order. If time remains on the order, Reissue is recommended because it is free and does not create a new order. Renew creates a new paid order. Users can use the optional `forceAction` field in the API request payload to explicitly specify either `renew` or `reissue`, as required.
csrGenerationSource	(Optional)Specifies how the CSR must be generated and provided during renewal, such as `appviewx`, `Use existing CSR`, or `uploadCSR`. Type: String
uploadCsrDetails	Mandatory when `csrGenerationSource` is set to `uploadCSR`. Type: Map<String, Object> Note: Upload CSR during renewal is supported for DigiCert and Hydrant ID CAs.
uploadCsrDetails.category	(Optional) Certificate category for the uploaded CSR, such as `Server` or `Client`. Type: String
uploadCsrDetails.csrContent	PEM-encoded CSR content that will be used for certificate renewal. Mandatory when `csrGenerationSource` is set to `uploadCSR`. Type: String

Response Structure

Response returns string of type application/json with the following body parameters:

Table 3. Parameters
Name	Description
response	Contains the response attributes for the renewal request.
resourceId `response`	Identifier of the certificate record that has been created. Type: String
requestId `response`	WorkOrder request Id. Type: String
message `response`	Success message - Renew action triggered successfully. Type: String
message	Success message or failure description in case of error. Type: String
appStatusCode	Application specific status code for the response. It is a non-null value for a failure response. Type: String
tags	Additional information in case of failure response.

Status Codes


HTTP Code	appStatusCode	Response Message
202 Accepted	null	Renew action has been triggered successfully.
401 Unauthorized	AVX_GW_003	Authentication failed, reason - Invalid Credentials. Remediation: Ensure that valid username and password or a valid sessionId is provided as header parameters.
400 Bad Request	INVALID_REQUEST	Invalid request specified Remediation: Ensure that the payload is valid
400 Bad Request	VALIDATION_ERROR_0004	Invalid serialNumber. Remediation: Ensure that the serialNumber is entered correctly
400 Bad Request	VALIDATION_ERROR_0004	Invalid resourceId. : Ensure that the resourceId is entered correctly.
417 Expectation Failed	READ_GROUP	Group is given with read permission, so cannot perform any operation. Remediation: Ensure the group associated with the certificate must have RW permission for the user.
417 Expectation Failed	OPEN_WORK_ORDERS_FOUND	Since requested certificate's work order is in progress, cannot initiate another action. Remediation: Trigger the request once the open work order for the certificate is completed.
417 Expectation Failed	CERT-CSR-0005	CSR submission failed. Remediation: Use the reissue option for this DigiCert certificate as the order for this certificate is still valid. If you still wish to renew, it will incur costs.
403 Forbidden	AVX_GW_005	User does not have access to the targeted API. Remediation: Ensure the user has ACF permission to renew certificates within the specified certificate’s category.
404 Not Found	NO_RECORDS_FOUND	No matching records found Remediation: Check and ensure that the values provided for commonName/ serialNumber/ resourceId are correct.
500 Internal Server Error	FAILED	Certificate Renew action failed during renewal submission due to CSR or private key is not available. Remediation: To renew, upload private key or CSR, or use regenerate option.
500 Internal Server Error	CANNOT_PERFORM_OPERATION	Cannot perform the specified operation. Probable cause: The specified action is not permitted for certificates in a monitored status.. Remediation: Change the status of the certificate from a monitored status to a managed status

Sample Request/Response

Request Payload

{
 "commonName":"testcert8g.appviewx.plus",
 "serialNumber":"0D:A9:2D:8C:90:BB:90:B0:CE:7D:6A:76:BF:70:75:81",
 "action":"Renew"
 }

Response

 {
 "response": {
 "resourceId": "5f4faf3e70040d33314f1142",
 "message": "Renew action triggered successfully.",
 "requestId": "209"
 },
 "message": "Renew action has been triggered successfully",
 "appStatusCode": null,
 "tags": {},
 "headers": null
 }

What's next?

References

Understanding the sample URL

IP/HostName/TenantName: Replace with the actual IP address, hostname, or tenant name based on the specific configuration in AppViewX.
- IP: A unique identifier assigned to each device connected to a computer network that uses the Internet Protocol for communication
  The IP address will be included in the endpoint URL for an on-prem deployment.
- HostName: A human-readable label assigned to a device (host) on a network
  The hostname will be included in the endpoint URL for an on-prem deployment.
- TenantName: An identifier label for a tenant given to indicate which tenant's data the API request will access/modify
  The tenant name will be included in the endpoint URL for a SaaS deployment.
GWPORT: AppViewX gateway port
A gateway port refers to a network port through which data is sent and received to communicate with a gateway in an on-prem deployment.
Example: 31443
avxapi: Path parameter value (static) that is part of the endpoint's URL
Endpoint: Endpoint of the API, for example: execute-hook
gwsource: Source or origin of a gateway, for example: external.