Revoke a Certificate in Async mode

The API initiates a request to revoke an existing certificate in asynchronous mode. Refer to the After you are done section to approve and implement the request.

Before you begin

Ensure the following before attempting to revoke a 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 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 param should be ‘application/json’
gwsource

Query

 (Mandatory) 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 (Optional) Unique Id of the certificate.

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 revocation.

Type: String

Possible values: Revoke
reason (Mandatory) Reason for revocation.

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 revoke 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 - Revoke 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 Revoke 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 worker 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 revoke 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
 {
 "resourceId":"5f4faf3e70040d33314f1142",
 "commonName":"testcert8g.appviewx.plus",
 "serialNumber":"0D:A9:2D:8C:90:BB:90:B0:CE:7D:6A:76:BF:70:75:81",
 "action":"Revoke",
 "reason":"Superseded"
 }
Response
{
"response": {
 "resourceId": "5f4faf3e70040d33314f1142",
 "message": "Revoke action triggered successfully.",
 "requestId": "216"
 },
 "message": "Revoke 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.