Download a Certificate by Format

The download certificate by format API initiates a request to download a certificate in the requested format. The user can request the private key to be downloaded in the specified format as well. The key can be requested with or without encryption. Additionally, the user can specify whether the complete certificate chain needs to be downloaded.

Before you begin

The user should have the ACF permission to download the certificate within the specified certificate’s category.
A certificate with the resource ID (or the common name and serial number combination) specified for deletion should already exist.
The group associated with the certificate should at least have the R permission.

Request Structure


Endpoint:	/certificate/download/format
Type:	POST
Sample URL:	`https://<IP/HostName/TenantName>:<GWPORT>/avxapi/certificate/download/format?gwsource=external` 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
Payload `Body`	The payload contains all the parameters to be included in the request body for the POST request. Type: Payload

Payload

Table 2. Payload
Name	Description
format	(Mandatory) The format of the certificate to be downloaded. Type: String Constraint: The possible certificate formats are - CRT, CERT, CER, PEM, DER, DERCER, P7B, P7C, PK8, P12, PFX, and JKS.
password	(Optional) Password for the certificate. It is applicable for the following certificate formats: P12, PFX, JKS, and PK8. (Mandatory) Password is mandatory for the following certificate formats: P12, PFX, and JKS. Type: String
commonName	(Mandatory if resourceId is not provided) Common name of the certificate. Type: String
serialNumber	(Mandatory) Serial number of the certificate to be downloaded. Type: String
resourceId	(Mandatory if commonName and serialNumber are not provided) Certificate ID to download the certificate content Type: String
isChainRequired	(Optional) Indicates whether to download the complete certificate chain or only the end certificate. Type: Boolean
isKeyEncryptionRequired	(Optional) Indicates whether the private key should be encrypted using a password. Type: Boolean Constraint: This is applicable for PK8 format. If the value is true, Ensure that the certificate policy allows private key access. The password must be provided in the request payload.

Response Structure


Status Code:	200 OK
Error Response:	The error response will have the parameters described below.
Headers
Content-Type:	application/octet-stream

Table 3. Error response parameters
Name	Description
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
200 OK	null	The attachment of the .pem type certificate.
404 Not Found	NO_RECORDS_FOUND	No matching records found. Remediation: Ensure that the value provided for commonName and serialNumber pertain to that of a valid existing certificate.
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>> Remediation: Ensure that the <<field>> is available in the request payload.
400 Bad Request	INVALID_FORMAT	Invalid format specified. Remediation: Ensure that a valid value is provided in the format field of the request.
417 Expectation Failed	NOT_A_VALID_CERT	Invalid certificate. Remediation: Certificates that have not yet been issued cannot be downloaded. Ensure that the resourceId refers to the certificate that has been issued.
417 Expectation Failed	CERT-KEY-0006	Private key access is restricted in <<Default>> policy. Remediation: Retry downloading the certificate after enabling the flag Enable Access to Private Key in the Certificate Policy.
417 Expectation Failed	CERT-HLST-0007	Failed to download as the given extension is not supported. Remediation: Ensure that a valid value is provided for the format field in the request.
417 Expectation Failed	PASSWORD_FORMAT_WRONG	Password must have at least eight characters and contain at least one lowercase letter, one uppercase letter, one numeric digit, and one special character. Remediation: Password provided in the request payload must have at least eight characters and contain at least one lowercase letter, one uppercase letter, one numeric digit, and one special character.

Sample Request/Response

Request Payload

{
"commonName" : "testcert7a.appviewx.com",
"serialNumber" : "07:2B:84:01:27:5A:77:63:38:C8:72:09:BE:CD:1F:D9:78:BA:BD",
"format" : "P12",
"password":"Password@123",
"isChainRequired":true,
"isKeyEncryptionRequired":false
}

Response

File is downloaded in the requested 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.