Create CA Policy

Before you Begin

Ensure the following before calling this API:

You have valid AppViewX credentials or an active session ID.
The AppViewX Native PKI module is enabled and accessible.
The CA to associate with the policy exists and is configured in AppViewX Native PKI.
The CA policy name you want to create does not already exist.

Request Structure


Endpoint:	`v1/pki/ca/policies`
Type:	`POST`
Sample URL:	`https://<IP/HostName/TenantName>:<GWPORT>/avxapi/v1/pki/ca/policies?gwsource=external` To understand the elements of the sample URL, see References.
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’
gwkey `Query`	(Mandatory) Tenant Key. This is needed only in case of multi-tenant installations and can disregarded for other types of installations. Type: String
gwsource `Query`	(Mandatory) Source from which the request is triggered. (E.g. external) Type: String
Payload `Body`	Contains all the parameters to be included in the request body for the POST request. Type: Payload

Payload Parameters


Parameter	Description
`policyName`	(Mandatory) Name of the CA policy. Type: String. Minimum 2 characters, maximum 64 characters.
`description`	Description of the CA policy. Type: String. Maximum 500 characters.
`caConfiguration`	(Mandatory) CA configuration settings for the policy. Type: Object.
`cryptographicSettings`	(Mandatory) Cryptographic settings for the CA policy. Type: Object.
`csrAndKeyGeneration`	(Mandatory) CSR and key generation settings. Type: Object.
`revocationAndDistribution`	(Mandatory) Revocation and distribution settings. Type: Object.

caConfiguration


Parameter	Description
`certificateAuthorityType`	(Mandatory) Type of CA. Type: String. Allowed values: `Root CA`, `Subordinate CA`.
`validFor`	(Mandatory) Allowed validity period range for certificates issued under this policy. Type: Array of Objects. Cannot be empty.
`pathLengthConstraint`	(Mandatory) Allowed range for the path length constraint, specified as a hyphen-separated string. Type: String. Example: `0-4`.

caConfiguration.validFor (array object)


Parameter	Description
`value`	(Mandatory) Minimum and maximum validity as a two-element array. Type: Array of Integer. Example: `[1, 5]`.
`unit`	(Mandatory) Unit for the validity period. Type: String. Allowed values: `Years`, `Months`.

cryptographicSettings


Parameter	Description
`cryptoModel`	(Mandatory) Cryptographic model. Type: String. Allowed values: `classical`, `pqc`, `composite`.
`keyDetails`	(Mandatory) Key algorithm details for the CA policy. Type: Array of Objects.
`eku`	Extended Key Usage values. Type: Array of String. Example: `["serverAuth", "clientAuth"]`.
`ku`	Key Usage values. Type: Array of String. Example: `["digitalSignature", "keyEncipherment", "crlSign"]`.

cryptographicSettings.keyDetails (array object)


Parameter	Description
`******Algorithm`	The available fields vary based on the selected cryptographic model: Classical: Uses `classicalAlgorithm`. PQC: Uses `pqcAlgorithm`. Composite: Uses both `classicalAlgorithm` and `pqcAlgorithm`. The fields displayed also depend on the selected algorithm. For example, some algorithms require a curve selection, while others require a key length. `classicalAlgorithm` — Specifies the classical cryptographic algorithm. Type: `String`. Example: `RSA`. (Mandatory) Classical cryptographic algorithm. Type: String. Example: `RSA`.
`padding`	Allowed padding algorithms. Type: Array of String. Example: `["PKCS1"]`.
`bitLength`	(Mandatory) Allowed key bit lengths. Type: Array of String. Example: `["2048"]`.
`hashAlgorithm`	(Mandatory) Allowed hash algorithms. Type: Array of String. Example: `["SHA256"]`.

csrAndKeyGeneration


Parameter	Description
`csrGeneration`	(Mandatory) CSR generation method. Type: String. Allowed values: `AppViewX`, `HSM`. Note: HSM support depends on the selected cryptographic model and algorithm: Classical: Supported for `RSA` and `EC`. PQC: Supported for `ML-DSA`. Composite: HSM is not supported.

revocationAndDistribution


Parameter	Description
`crlPublish`	Enables CRL publishing for certificates issued under this policy. Type: Boolean. If `true`, `crlSign` must be included in `ku`.
`crlDistributionPoints`	Protocols for CRL distribution. Type: Array of String. Allowed values: `HTTP`.
`defaultOcspSigningCertificate`	Algorithm for the default OCSP signing certificate. Type: String. EC algorithm is not allowed.
`defaultCsrGenerationForOcspSigningCertificate`	CSR generation method for the OCSP signing certificate. Type: String. Allowed values: `AppViewX`. HSM is not allowed.

Response Structure

The response returns a string of type application/json with the following body parameters:


Parameter	Description
`response`	Indicates the status of the create operation. Type: String or Object.
`message`	Success or error message. Type: String.
`appStatusCode`	Application-specific status code for the response. Non-null for failure responses. Type: String.
`tags`	Additional information in case of a failure response.

Status Codes


HTTP Status	appStatusCode	Description
`200 OK`	null	CA policy created successfully.
`400 Bad Request`	`MANDATORY_POLICY_NAME`	Policy name is missing or empty. Remediation: Provide a value for `policyName` (2–64 characters).
`400 Bad Request`	`INVALID_POLICY_NAME_LENGTH`	Policy name must be between 2 and 64 characters. Remediation: Adjust the length of `policyName`.
`400 Bad Request`	`KEY_DETAILS_VALIDATION_FAILED`	Validation failed for the key details in the policy. Remediation: Verify that `keyDetails` contains valid algorithm, bit length, and hash algorithm values.
`400 Bad Request`	`CRL_SIGN_MUST_PRESENT_IN_KU_FOR_CRL_PUBLISH`	`crlPublish` is set to `true` but `crlSign` is not included in `ku`. Remediation: Add `crlSign` to the `ku` array.
`400 Bad Request`	`INVALID_OCSP_SIGNING_CERTIFICATE_ALGORITHM`	EC is not a valid algorithm for `defaultOcspSigningCertificate`. Remediation: Use a non-EC classical algorithm.
`400 Bad Request`	`INVALID_OCSP_CSR_GENERATION_TYPE`	HSM is not a valid value for `defaultCsrGenerationForOcspSigningCertificate`. Remediation: Use `AppViewX`.
`400 Bad Request`	`HSM_NOT_SUPPORTED_FOR_PQC_OR_COMPOSITE`	HSM support depends on the selected cryptographic model and algorithm: Classical: Supported for `RSA` and `EC`. PQC: Supported for `ML-DSA`. Composite: HSM is not supported. . Remediation: Use `AppViewX` for `csrGeneration`.
`401 Unauthorized`	`AVX_GW_003`	Authentication failed — invalid credentials. Remediation: Provide a valid `username` and `password` or a valid `sessionId`.
`403 Forbidden`	`USER_POLICY_WRITE_ACCESS_RESTRICTED`	The authenticated user does not have write access to CA policies. Remediation: Contact your AppViewX administrator to grant the required permissions.
`409 Conflict`	`POLICY_NAME_ALREADY_EXISTS`	A CA policy with the specified name already exists. Remediation: Provide a unique value for `policyName`.

Sample Request/Response

Sample Request

{
  "policyName": "RootCAPolicy-PQC-ML-DSA",
  "description": "Root CA policy with PQC ML-DSA key details",
  "caConfiguration": {
    "certificateAuthorityType": "Root CA",
    "validFor": [
      {
        "value": [
          1
        ],
        "unit": "Years"
      }
    ],
    "pathLengthConstraint": "0-4"
  },
  "cryptographicSettings": {
    "cryptoModel": "pqc",
    "keyDetails": [
      {
        "keyDetailsType": "PqcKeyDetails",
        "pqcAlgorithm": "ML-DSA",
        "bitLength": [
          "15616"
        ],
        "hashAlgorithm": [
          "SHAKE256"
        ]
      }
    ],
    "eku": [
      "serverAuth"
    ],
    "ku": [
      "digitalSignature",
      "crlSign"
    ]
  },
  "csrAndKeyGeneration": {
    "csrGeneration": "AppViewX"
  },
  "revocationAndDistribution": {
    "crlPublish": true,
    "crlDistributionPoints": [
      "HTTP"
    ],
    "defaultOcspSigningCertificate": "RSA",
    "defaultCsrGenerationForOcspSigningCertificate": "AppViewX"
  }
}

Sample Response

{
  "response": "Success",
  "message": "CA policy created successfully",
  "appStatusCode": 0,
  "tags": {},
  "headers": {
    "additionalProp1": {}
  }
}

Important: Policies created through the API are immediately visible and usable in the AppViewX Native PKI UI. Policies created in the UI can also be retrieved and managed through this API.

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.