Renew a Certificate in Sync mode

The API initiates a certificate regenerate request in Sync Mode, which differs from asynchronous APIs by using two distinct parameters: isSync and ttl. To enable the synchronous mode for processing certificate requests, set isSync to true. These parameters can be applied to all the Certificate Authorities (CAs) listed in the asynchronous APIs.

Before you begin

The user should have the ACF permission to renew certificates within the specified certificate’s category.
The certificate to be renewed should not be in the revoked or monitored state.
The CA connector for the certificate should be available.
The certificate should be present in a group that has RW permission.
There should be no open work orders available for the certificate.
The certificate should be present in AppViewX, with either its CSR/ private key along with it.
The newly renewed certificate will fall under the same group as the existing certificate.
The CA must configured in AppViewX from the Certificate Authority page.
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/renew
Type:	PUT
Sample URL:	`https://<IP/HostName/TenantName>:<GWPORT>/avxapi/certificate/renew?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
userName `Header`	(Mandatory) Username that is configured in AppViewX. Type: String
password `Header`	(Mandatory) Password of that user. Type: String
content-type `Header`	(Mandatory) Payload content-type with application/json value. Type: String Constraint: The value must be application/json.
gwsource `Query`	(Mandatory) The source from which the request is triggered, e.g., external. Type: String
isSync `Query`	(Optional) Processing mode for the regeneration request To enable the synchronous processing mode, set this to true. Type: Boolean Possible values: true, false Constraint: The value must be a boolean type: true or false.
ttl `Query`	(Optional) Duration (in seconds) for which the API response remains available for retrieval after the regeneration request is processed After this duration lapses, the response may no longer be accessible Type: Integer Default value: 300 seconds Constraint: The value must be a positive integer.
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	(Mandatory) Mongo ID of the certificate in the AppViewX database. (It refers to the resourceId field in the create certificate response.) Type: String Constraint: Either resourceId or serialNumber and commonName is mandatory.
commonName	(Mandatory) Common name of the certificate. Type: String Constraint: Either resourceId or serialNumber and commonName is mandatory. Note: `commonName` field is optional for Code Signing certificates.
serialNumber	(Mandatory) Serial number of the certificate. Type: String Constraint: Either resourceId or serialNumber and commonName is mandatory.
certificateFormat	(Mandatory) Certificate format and access details Type: certificateFormat
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

Table 3. certificateFormat
Name	Description
format	(Mandatory) Certificate downloadable format. Type: String Constraint: For the possible values for the certificate download format, click here.
password	(Mandatory) The field is mandatory for some parameters. Type: String Constraint: For the possible values for the certificate download format, click here.

Table 4. Possible values for certificate download format
Certificate Extension	Value in the Payload	Password Required
.crt	CRT	No
.cert	CERT	No
.cer	CER	No
.pem	PEM	No
.der	DER	No
.cer	DERCER	No
.p7b	P7B	No
.p7c	P7C	No
.pk8	PK8	No
.pk12	PK12	Yes
.pfx	PFX	Yes
.jks	JKS	Yes

Response Structure

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

Table 5. Parameters
Name	Description
response	Contains the response attributes for the enrollment request.
resourceId `response`	Identifier of the certificate record that has been created. Type: String
requestId `response`	Open work order request ID. Type: String
certificateContent `response`	Content of certificate in Base64 encoded format. Type: String
encodedFormat `response`	Certificate content in encoded format. Type: String
certificateName `response`	Name of the certificate. 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 resourceId is entered correctly
400 Bad Request	VALIDATION_ERROR_0004	Invalid resourceId Remediation: Ensure that the resourceId is entered correctly
400 Bad Request	MANDATORY_FIELD_MISSING	Either resourceId or commonName & serialNumber are Mandatory Remediation: Please ensure either resourceId or commonName & serialNumber are entered
400 Bad Request	MANDATORY_FIELD_MISSING	Mandatory field is missing or invalid - commonName. Remediation: Ensure that the commonName field is available in the request payload.
400 Bad Request	MANDATORY_FIELD_MISSING	Mandatory field is missing or invalid - serialNumber. Remediation: Ensure that the serialNumber field is available in the request payload.
400 Bad Request	VALIDATION_ERROR_0004	Validation Failure: Field format does not have the expected value Remediation: Please ensure format is entered from the possible values for certificate download format.
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
406 Not Acceptable	CERT-VWF-0006	Life cycle action is unsupported by CA or another work order is in progress or certificate belongs to read group or is in Monitored status. Remediation: Ensure the following: The CA supports the renew action. There is no workOrder in progress for the specified certificate. Certificate does not belong to read only group. Certificate is not in the monitored status.
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-GEN-0055	orderValidityUnit and orderValidityUnitValue field inside caConnectorInfo.vendorSpecificDetails or validityUnit and validityUnitValue is mandatory Remediation: Ensure valid values are assigned to the mandatory fields.
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
500 Internal Server Error	FAILED	Certificate Renew action performed successfully but failed to download. Reason - Mandatory field is missing or invalid - format Remediation: Please ensure certificateFormat.format is entered in the payload.
500 Internal Server Error	avx-common-011	Error while processing

Sample Request/Response

Request Payload

{
 "resourceId":<Mongo ID of the certificate in AppviewX Database>,
 "workflowType": "direct",
 "commonName":<Common Name of the certificate>,
 "serialNumber":<Serial Number of the certificate>,
 "certificateFormat":{
 "format" :<Cert format - check possible values table>,
 "password" :<password>
 }
 }

Response

{
    "response": {
        "certificateContent": "<Base64 encoded cert content>",
        "privateKeyContent": "",
        "resourceId": "<renewed cert ID>",
        "requestId": "<Certificate direct request ID>",
        "externalRequestId": null,
        "newCertificateUuid": "<Renewed cert UUID>",
        "newCertificateId": "<renewed cert ID>"
        "keyAlreadyExist": false,
        "tags": null
    },
    "message": "Certificate retrieved successfully from CA",
    "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.