Create a Certificate in Async mode

The API initiates the creation of a new certificate in async mode. This mode requests certificate generation and provides a request ID in the response. The request payload varies depending on the Certificate Authority (CA) used for enrollment. After successfully triggering the create certificate API, the response includes the resourceId, which can be used to activate the search API and retrieve the created certificate. Please refer to the After you are done section for instructions on approving and implementing the request.

Before you begin

Ensure the following before attempting to enroll a certificate from a particular CA through AppViewX:

The CA must configured in AppViewX from the Certificate Authority page.
The user should have the ACF permission to submit certificates within the specified certificate’s category.
The group associated with the certificate must have RW permission.
Connectivity to the CA via the chosen setting should be working correctly.
A certificate group should be created and associated with the policy. If not, the certificate will be created under the Default group.
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/create
Type:	POST
Sample URL:	`https://<IP/HostName/TenantName>:<GWPORT>/avxapi/certificate/create?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) AppViewX login username. Type: String Constraint: Required if sessionId is not provided.
password `Header`	(Mandatory) 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 parameter 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 post request. Type: Payload

Payload

Table 2. Payload
Name	Description
csrGenerationSource	(Optional) Specifies where the CSR is to be generated. Type: Possible values:: appviewx, uploadCSR, ENDPOINT, hsm. Default value: appviewx
templateName	(Optional) Specifies the policy template to be used for certificate enrollment. Type: templateName Possible values: Any custom value
caConnectorInfo	(Mandatory) Details related to the certificate authority (CA) and the CSR parameters. Type: Any of the following data: Amazon caConnectorInfo AppViewX caConnectorInfo DigiCert caConnectorInfo EJBCA caConnectorInfo Entrust caConnectorInfo EntrustMPKI caConnectorInfo GlobalSign caConnectorInfo GoDaddy caConnectorInfo Google caConnectorInfo InCommon caConnectorInfo LetsEncrypt caConnectorInfo Microsoft Enterprise caConnectorInfo Microsoft Standalone caConnectorInfo OpenTrust caConnectorInfo Sectigo caConnectorInfo Symantec caConnectorInfo Trustwave caConnectorInfo
certificateGroup	Specifies the group (category) to which the newly created certificate should be assigned. Type: certificateGroup Constraint: Default certificate Group is "Default".
deviceDetails	(Optional) Information about the device or endpoint where the Certificate Signing Request (CSR) will be generated. Type: deviceDetails Constraint: It is mandatory if csrGenerationSource is Endpoint.
certificateHSMDetails	(Optional) Information about the Hardware Security Module (HSM) device. Type: certificateHSMDetails Constraint: It is mandatory if csrGenerationSource is HSM.
uploadCsrDetails	(Optional) Information about the CSR. Type: uploadCsrDetails Constraint: It is mandatory if csrGenerationSource is uploadCSR.
certificateFormat	(Optional) Certificate download format details. Type: certificateFormat

Table 3. certificateGroup
Name	Mandatory
name	(Optional) Specifies the group under which the created certificate needs to be tagged. Type: String Constraint: The certificate group must be present in AppViewX.

Table 4. deviceDetails
Name	Mandatory
category	(Mandatory) Specifies the device category Type: String Possible values: ADC, Server, and Firewall.
vendor	(Mandatory) Name of the vendor for the chosen device. For example, Apache is a vendor for Server category. Type: String
deviceName	(Mandatory) Name of the device as per AppViewX Device Inventory. Type: String
csrFileName	(Mandatory) Name of the CSR file that is generated in the device. Type: String
keyFileName	(Mandatory) Name of the key file that is generated in the device. Type: String
attributes	(Optional) Additional attributes for the chosen device as mentioned the sub-attributes - csrLocation, tenant, and partition. Type:
csrLocation `attributes`	(Optional) The location within the device where the CSR is generated. Type: String Constraint: It is mandatory when deviceDetails.category is Server and the deviceDetails.vendor is Tomcat.
tenant `attributes`	(Optional) Name of the partition within the AVI device. Type: String
partition `attributes`	(Optional) Name of the partition within the device. Type: String Constraint: It is mandatory when deviceDetails.category is Friewall and the deviceDetails.vendor is Fortinet.

Table 5. certificateHSMDetails
Name	Mandatory
type	(Mandatory) Type of the HSM device. Type: String Possible values: ADC and HSM.
keyReference	(Mandatory) Reference name for the key that is mapped by the HSM device. Type: String
hsmSettings	(Mandatory) Configuration details for the HSM device. Contains the sub-parameters vendorType and vendorSpecificSettings Type: List <String>
vendorType`hsmSettings`	(Mandatory) Category of the vendor. Type: String Possible values: Safenet, Thales, and Fortanix.
vendorSpecificSettings`hsmSettings`	(Mandatory) Settings related to HSM vendor. Contains the sub-parameter moduleId Type: String
moduleId `hsmSettings. vendorSpecificSettings`	(Optional) The module id. Type: String Constraints: Applicable if hsmSettings.vendorType is Thales.
vendor	(Mandatory) The name of the vendor for the chosen device e.g., F5. Type: String
deviceName	(Mandatory) The name of the device as per AppViewX Device Inventory. Type: String

Table 6. uploadCsrDetails
Name	Mandatory
category	(Mandatory) Certificate category Type: String Possible values: Server, Client, and Code Signing
csrContent	(Mandatory) The CSR content for certificate enrollment request Type: String

Table 7. certificateFormat
Name	Mandatory
format	(Mandatory) Certificate download format. Refer to the Possible values for Certificate Download Format table. Type: String
password	(Optional) The field is mandatory for some parameters (refer to the table below). Type: String

Table 8. Possible Values for 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 9. Parameters
Name	Description
response	Contains the response attributes for the enrollment request. Type: Object
resourceId `response`	Identifier of the certificate record that has been created (the resourceId in the above request can be found using the search API using commonName, serial No. or other search parameters). Type: String
requestId `response`	Open work order request ID. 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 for failure response. Type: String
tags	Additional information in case of a failure response. Type: Object

Status Codes


HTTP Code	appStatusCode	Response Message
202 Accepted	NA	Certificate submission triggered successfully.
401 Unauthorized	AVX_GW_003	Authentication failed, reason - Invalid Credentials. Remediation: Ensure that valid username and password or valid sessionId is provided as header parameters.
400 Bad Request	MANDATORY_FIELD_MISSING	Mandatory field is missing or invalid - <<field name>> Remediation: Ensure that a valid value is provided for the <<field name>> field in the request.
400 Bad Request	INVALID_CSR_GEN_SOURCE	Invalid csr generation source specified. Remediation: Ensure that a valid value is provided for the csrGenerationSource field in the request.
417 Expectation failed	READ_GROUP	Group is given with read permission, so cannot perform any operation. Remediation: Ensure that the field csrGenerationSource field has read write permission.
404 Expectation failed	GROUP_NOT_FOUND	Invalid group name specified. Remediation: Ensure that a valid value is provided for the certificateGroup section in the request.
404 Not Found	CERT-CA-0001	CA settings are not available. Remediation: Ensure that a valid value is provided for the caSettingName section in the request.

What's next?

Add Certificate Attributes

Download a Certificate

Download a Certificate by Format

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.