Create a Certificate in Sync mode

The API sends a request for certificate creation in the sync mode, where the certificate is generated immediately and returned in the response. The request payload differs based on the Certificate Authority (CA) for which enrollment or creation is being requested. Unlike async APIs, two parameters, isSync and ttl, stand out. To enable the synchronous mode for processing certificate requests, set isSync to true. These parameters are applicable to all CAs mentioned in the async APIs.

Before you begin

  • 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&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) 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
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 post request.

Type: Payload

Payload

Table 2. Payload
Name Description
csrGenerationSource (Optional) Specifies where the CSR is to be generated.

Type:

Possible values:: AppViewX, Endpoint, HSM, uploadCSR. The default value is 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:
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 (Mandatory) 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>
vendorTypehsmSettings (Mandatory) Category of the vendor.

Type: String

Possible values: Safenet, Thales, and Fortanix.
vendorSpecificSettingshsmSettings (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 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 params:

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
certificateContent

response

 Content of certificate in Base64 encoded format.

Type: String
encodedFormat

response

 Certificate content encoded format.

Type: String
certificateName

response

 Certificate name.

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 INVALID_REQUEST Invalid request specified

Remediation: Ensure that the payload is valid.
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.
400 Bad Request INVALID_TTL_VALUE Please provide valid integer for ttl.

Remediation: Ensure the value of ttl in query params is an integer.
417 Expectation failed READ_GROUP Group is given with read permission, so cannot perform any operation.

Remediation: Ensure that the group associated with the certificate has read write permissions for the user.
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.
417 Expectation Failed READ_GROUP Group is given with read permission, so cannot perform any operation.

Remediation: Ensure group name entered in the payload has RW permissions.
417 Expectation Failed FAILED Certificate create action in progress during CSR Submission.

Remediation: Ensure the test connection is successful.
417 Expectation Failed FAILED Certificate create action Failed during CSR Submission due to Unable to submit the CSR request to certificate authority.-validity_years contains an invalid value

Remediation: Ensure that the validity in your CSR request is set to a valid number
403 Forbidden AVX_GW_005 User does not have access to the targeted API.

Remediation: Ensure the user has ACF permission to enroll/submit certificates within the specified certificate’s category.
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-PLCY-0003 Policy information not available

Remediation: Ensure if Certificate Authority mapping is available in the Certificate Policy of the group mentioned in the payload
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.

Sample Request/Response

Request Payload
 {
 "caConnectorInfo": {
 "caSettingName": "",
 "validityInDays": 365,
 "isAutoRenewal": "true",
 "renewBefore": "30",
 "autoRegenerateEnabled": false,
 "certificateType": "",
 "csrParameters": {
 "commonName": "",
 "organization": "",
 "organizationUnit": "",
 "locality": "",
 "state": "",
 "country": "",
 "mailAddress": "",
 "encryptedChallengePassword": "",
 "hashFunction": "",
 "keyType": "",
 "bitLength": "",
 "certificateCategories": [
 "Server",
 "Client"
 ],
 "ellipticCurve": "",
 "enhancedSANTypes": {
 "dNSNames": [],
 "iPAddresses": [],
 "uniformResourceIdentifiers": []
 }
 }
 "genericFields": {
 "device_name_Entrust": "",
 "vs_ip_Entrust": "",
 "type": "",
 "owner_email": "",
 "environment": "",
 "partition": "",
 "devices": "",
 "sync_group": "",
 "requestor": "",
 "project": ""
 },
 "vendorSpecificDetails": {
 "avx_requester_fullname":"",
 "avx_requester_emailid":"",
 "avx_requester_phoneno": "",
 "additionalEmails": ""
 },
 "customAttributes": {
 "attribute1": ""
 }
 },
 "certificateGroup": {
 "name": "Default"
 },
 "certificateFormat": {
 "format": "PEM",
 "password": ""
 }
 }
Response
 {
 "response": {
 "resourceId": "<Certificate Object ID>",
 "requestId": "<Certificate WF Request ID>",
 "certificateContent": "<Encoded Certificate Content>",
 "encodedFormat": "base64",
 "certificateName": "<Name of the Certificate>"
 },
 "message": "Certificate create and download action performed successfully",
 "appStatusCode": "<Error Code>",
 "tags": {},
 "headers": null
 }

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.