Reissue a Certificate in Async mode

The API will initiate a request to reissue an existing certificate in asynchronous mode. Upon successful triggering of the "Reissue a certificate" API, the response will include a resourceId. This resourceId can be used 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 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/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 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
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, serialNunmer. or other search parameters.)

Type: String

Constraint: Common name and either resourceId or serialNumber is mandatory.
commonName (Mandatory) Common name of the certificate.

Type: String

Constraint: Common name and either resourceId or serialNumber is mandatory.

Note: commonName field is optional for Code Signing certificates.
serialNumber (Mandatory) Serial number of the certificate.

Type: String

Constraint: Common name and either resourceId or serialNumber is mandatory.
action (Mandatory) Action name for the reissue

Type: String

Possible values: Reissue
reason (Mandatory) Reason for reissue request

Type: String
certificateFormat (Mandatory) Certificate format and access details

Type: certificateFormat
uploadCSRDetails (Mandatory) Information related to the CSR

Type: uploadCSRDetails
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
Table 5. 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

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

 Work order request Id.

Type: String
message

response

 Success message - Reissue 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 Reissue 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.
404 Not Found NO_RECORDS_FOUND No matching records found.

Remediation: Check and ensure that the values provided for commonName / serialNumber / resourceId are correct.
400 Bad Request INVALID_REQUEST Please give valid common name and serial number or resourceId.

Remediation: Provide a valid commonName and serialNumber or resourceId.
400 Bad Request INVALID_REQUEST Please provide a valid action.

Remediation: Provide a valid action.
400 Bad Request MANDATORY_FIELD_MISSING Mandatory field is missing or invalid - action.

Remediation: Ensure that the action field is available in the request payload.
400 Bad Request MANDATORY_FIELD_MISSING Mandatory field is missing or invalid - reason.

Remediation: Ensure that the reason field is available in the request payload.
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 workOrder for the certificate is completed.
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 reissue 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.

Sample Request/Response

Request Payload
{
"commonName":"testcert8g.appviewx.plus",
 "serialNumber":"08:BD:54:35:FD:81:AC:A4:45:2B:FC:9F:77:56:FE:2C",
 "action":"Reissue",
 "reason":"Superseded"
 }
Response
{
"response": {
"resourceId": "5f51f7312fa95059a12b0aee",
"message": "Reissue action triggered successfully.",
"requestId": "238"
},
"message": "Reissue 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.