Regenerate 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 ACF permission to regenerate the certificate under the associated certificate category.
  • The group associated with the certificate must have RW permission.
  • The certificate to be regenerated should not be in the 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 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/regenerate
Type: PUT
Sample URL: 
https://<IP/HostName/TenantName>:<GWPORT>/avxapi/certificate/regenerate?gwsource=external&isSync=true&ttl=300&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 only if sessionID is not provided) Username that is configured in AppViewX.

Type: String
password

Header

 (Mandatory only if sessionID is not provided) 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. It can be found through the search API using commonName, serialNumber. or other search parameters.)

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) Configuration for downloading the certificate

Type: certificateFormat
Table 3. certificateFormat
Name Description
format (Mandatory) Certificate download format.

Type: String

Constraint: Refer to the possible values here.
password (Mandatory) The field is mandatory for some parameters.

Type: String

Constraint: Refer to the possible values 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
.p12 P12 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 regenerate 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 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 OK null Certificate regenerate action performed 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.

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: Please ensure commonName is entered in the payload.
400 Bad Request MANDATORY_FIELD_MISSING Mandatory field is missing or invalid - serialNumber

Remediation: Please ensure serialNumber is entered in the 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 reissue 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.
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.
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 regenerate 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>,
 "commonName":<Common Name of the certificate>,
 "serialNumber":<Serial Number of the certificate>,
 "certificateFormat":{
 "format" :<Cert format - check possible values table>,
 "password" :<password>
 }
 }
Response
{ 
 "response": {
 "resourceId": "<Certificate ID>",
 "requestId": "<Certificate WF Request ID>",
 "certificateContent": <Encoded Certificate file>,
 "certificateName": <Name of the certificate>,
 "encodedFormat" : "base64"
 },
 "message": "Certificate Regenerate action executed successfully",
 "appStatusCode": "<Error Code>",
 "tags": {},
 "headers": null
 }

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.