Reissue 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 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 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/reissue
Type: PUT
Sample URL: 
https://<IP/HostName/TenantName>:<GWPORT>/avxapi/certificate/reissue?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
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) Unique 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.
reason (Mandatory) Reasons for reissuing the certificate.

Type: String

Constraint: Either resourceId or serialNumber and commonName is mandatory.
uploadCSRDetails (Mandatory) Information related to the CSR

Type: uploadCSRDetails
certificateFormat (Mandatory) Configuration for certificate download

Type: certificateFormat
Table 3. uploadCSRDetails
Name Description
category (Mandatory) Certificate category.

Type: String

Constraint: Possible values - Server, Client, or Code Signing.
csrContent (Mandatory) The CSR content for certificate enrollment request

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

Type: String

Constraint: Refer to the possible values for certificate download format table.
password (Mandatory) The field is mandatory for some parameters.

Type: String

Constraint: Refer to the possible values for certificate download format table.
Table 5. 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 6. Parameters
Name Description
response Contains the response attributes for the reissue 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 Accepted null Certificate reissue action performed successfully.
202 Accepted SUCCESS

Certificate reissue action is in progress and waiting in Awaiting Certificate Retrieval

Remediation: Approve the certificate request in the respective CA portal.
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 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 Invalid resourceId.

Remediation: Ensure that the resourceId is entered correctly.
400 Bad Request INVALID_REQUEST Invalid commonName and serialNumber or resourceId.

Remediation: Enter a valid commonName and serialNumber or resourceId.
400 Bad Request MANDATORY_FIELD_MISSING Mandatory field is missing or invalid - category. Probable Cause: The Category field is not specified within the uploadCsrDetails during the certificate enrollment.

: Please ensure that the Category field is correctly provided within the uploadCsrDetails during the certificate enrollment.
400 Bad Request MANDATORY_FIELD_MISSING

Mandatory field is missing or invalid - category. Probable Cause: The \"Category\" field is not specified within the \"uploadCsrDetails\" during the certificate enrollment.

Remediation: Please ensure that the "Category" field is correctly provided within the "uploadCsrDetails" during the certificate enrollment.
400 Bad Request FAILED Certificate reissue 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
400 Bad Request INVALID_TTL_VALUE Please provide valid integer for ttl.

Remediation: Eensure the value of ttl in query params is an integer.
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 CERT-CA-0001 CA settings are not available.

Remediation: Ensure valid CA settings are entered in the payload.
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.
417 Expectation Failed CERT-GEN-0002 Reissue is not supported for the certificates whose CSRs were generated with HSM ADC devices.

Remediation: Use Regenerate option
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 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
{
"resourceId": "<Mongo ID of the certificate in AppviewX Database>",
 "commonName": "<Common Name of the certificate>",
 "serialNumber": "<Serial Number of the certificate>",
 "reason": "<Reason for reissue>",
 "uploadCsrDetails": {
 "csrContent": "",
 "additionalSANValues": {
 "dNSNames": [],
 "iPAddresses": [],
 "uniformResourceIdentifiers": []
 }
 },
 "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 Reissue action executed successfully"
 "appStatusCode": "<Error Code>",
 "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.