Create Subordinate CA

Before you begin

Ensure the following before attempting to renew certificate from any CA through AppViewX:

Refer to Prerequisites in the PKI User Guide.

Request Structure


Endpoint:	v1/pki/ca/create-ca
Type:	POST
Sample URL:	`https://<IP/HostName/TenantName>:>GWPORT>/avxapi/v1/pki/ca/create-ca?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 Type: String
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
policyName	(Mandatory) Name of the Sub CA policy. Type: String
name	(Mandatory) Name of the sub CA. Type: String
description	(Optional) Description for the sub CA. Type: String
rootCAName	(Mandatory) Name of the root CA under which this subordinate CA will be created. Type: String
validityUnitValue	(Mandatory) Duration of certificate validity. Type: String
validityUnit	(Mandatory) Unit of validity (e.g., years, months). Type: String
maxIssuerPathLength	(Mandatory) Maximum number of intermediate CAs that can follow this CA (or `"NONE"`). Type: String
templateName	(Mandatory) Name of the certificate template to apply. Type: String
issuerMaxLength	(Mandatory) Max length of issuer path, possibly for constraint enforcement. Type: String
caType	(Mandatory) Type of CA being created (Sub CA in this case). Type: String

Table 3. pkiKeySpec
Name	Description
keyGenerationSource	(Mandatory) Source of the key (e.g., "AppViewX", "HSM") Type: String

Table 4. keyAlgorithmSpecification
Name	Description
cryptoModel	(Mandatory) Select the cryptographic model that defines the type of algorithms used by this Certificate Authority hierarchy. Accepted values are: classical, pqc, composite. Type: String
keyAlgorithm	(Mandatory) Only the keyAlgorithm selected in policy are accepeted. The values are derived based on crypto model and keyTypes combination in the policy. Type: String Example: RSA, ML-DSA
bitLength	(Mandatory) Only the bitLength selected in policy are accepeted. The values are derived based on crypto model, keyTypes and bitLength combination in the policy. Type: String Example: 2048, 10496
hashAlgorithm	(Mandatory) Only the hashAlgorithm selected in policy are accepeted. The values are derived based on crypto model, keyTypes and hashAlgorithm combination in the policy. Type: String Example: SHA256, SHAKE256

Table 5. csrParameters
Name	Description
organization	(Mandatory) Organization name Type: String
organizationUnit	(Optional) Department or unit Type: String
locality	(Optional) City or location Type: String
state	(Optional) State or province Type: String
country	(Optional) Country code Type: String
commonName	(Mandatory) Common name for the sub CA Type: String

Table 6. CRL Service
Name	Description
skipCRLService	(Optional) To enable CRL services during CA creation, set `"skipCRLService": false`. To disable CRL services, set `"skipCRLService": true`. Note: Ensure the selected template includes the cRLSign key usage to enable CRL services. If not, a warning is displayed, and you must update the template or disable CRL services to proceed. Type: Boolean

Response Structure

Response returns string of type application/json with the following body parameters:

Table 7. Parameters
Name	Description
response	Indicates status of the API operation.
message	Success message - PKIaaS CA configuration added successfully 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 Accepted	null	Create sub CA 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.
400 Bad Request	INVALID_TEMPLATE	Occurs when specified template is not present. Remediation: Ensure that specified template is selected.
400 Bad Request	VALIDATION_ERROR_0004	Occurs when type of value in invalid. Remediation: Provide valid input value. Example: validityUnit is string but integer is given.
400 Bad Request	ISSUING_CA_CONFIG_NOT_FOUND	Occurs when the rootCA name is not found for sub CA creation. Remediation: Ensure rootCA name is present.
400 Bad Request	HSM_DETAIL_NOT_FOUND_IN_KEYSPEC	Occurs when keyGenerationSource is HSM, but keyHandlerName or hsmDeviceName is not present. Remediation: Provide all fields required for HSM.
400 Bad Request	CRL_SERVICE_MUST_BE_ENABLED_WHEN _KU_HAS_CRL_SIGN	CRL publishing is enabled, but the selected template does not include cRL Sign in the Key Usage extension. Please update the template or disable CRL publishing to proceed. Remediation: Update the template with cRL Sign in Key Usage extension or Disable the CRL Service.
417 Expectation Failed	CA_CONFIG_NAME_EXIST	Occurs when CA name already exists. Remediation: Provide a unique CA name.
400 Bad Request	ROOT_CA_NAME_MANDATORY_FOR_SUB_CA	Occurs when the rootCAName field in payload for sub ca creation is not given. Remediation: Ensure that the rootCAName field in payload for sub ca creation is provided.

Sample Request/Response

Request Payload

{
  "policyName": "SUBPQCPolicy",
  "name": "SubCAPKI",
  "validityUnitValue": "30",
  "validityUnit": "years",
  "maxIssuerPathLength": "NONE",
  "templateName": "SubCA_Default",
  "caType": "Subordinate CA",
  "keyAlgorithmSpecification": {
    "cryptoModel": "pqc",
    "keyAlgorithm": "FN-DSA",
    "bitLength": "14344",
    "hashAlgorithm": "SHAKE256"
  },
  "pkiKeySpec": {
    "keyGenerationSource": "AppViewX"
  },
  "csrParameters": {
    "organization": "AppViewX Inc.",
    "organizationUnit": "PE",
    "locality": "CBE",
    "state": "TN",
    "country": "IN",
    "commonName": "Sub Certificate Authority"
  },
  "skipCRLService": true
}

Response


{
    "response": "Success",
    "message": "PKIaaS CA configuration added successfully.",
    "appStatusCode": null,
    "tags": {},
    "headers": null
}

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.