Renew CA

Before you Begin

Ensure the following before you renew a CA certificate:

The CA exists in AppViewX.
A valid certificate template is available for the renewal.
You have resource-level access to the CA.
If you plan to use post-quantum cryptography (PQC) algorithms, make sure the AppViewX environment supports them and the algorithm names follow the current naming convention. Legacy PQC algorithm names are not accepted.
Refer to Prerequisites in the PKI User Guide.

Request Structure


Endpoint:	`v1/pki/ca/<CAName>/renew-ca`
Type:	`POST`
Sample URL:	`https://<IP/HostName/TenantName>:<GWPORT>/avxapi/v1/pki/ca/<CAName>/renew-ca?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 provides.
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 be disregarded for other types of installations. Type: String
gwsource `Query`	(Mandatory) Source from which the request is triggered. (E.g. external) Type: String
CAName `Path`	(Mandatory) The name of the CA to renew. Replace `<CAName>` in the URL with the actual CA name. 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
`templateName`	(Mandatory) Name of the certificate template to use for the renewed CA certificate. The name can contain letters, numbers, hyphens, underscores, dots, and spaces. Type: String.
`validityUnit`	(Mandatory) Unit for the new validity period. Type: String. Allowed values: `months`, `years`.
`validityUnitValue`	(Mandatory) Number of months or years for which the renewed CA certificate is valid. Type: Integer.
`policyName`	(Optional) Name of the certificate policy to apply during renewal. Type: String.
`csrParameters`	(Mandatory) Subject details for the renewed CA certificate. Type: Object.

csrParameters


Parameter	Description
`commonName`	(Mandatory) The common name for the renewed CA certificate. Type: String.
`organization`	(Mandatory) The name of the organization that owns the CA. Type: String.
`organizationUnit`	(Optional) The department or unit within the organization. Type: String.
`locality`	(Optional) The city or location of the organization. Type: String.
`state`	(Optional) The state or province of the organization. Type: String.
`country`	(Optional) The two-letter country code of the organization. For example: `US`. Type: String.

Response Structure

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


Parameter	Description
`response`	Indicates the status of the renew 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	The renew CA action was triggered successfully.
`400 Bad Request`	`INVALID_PAYLOAD`	The CA name in the URL does not match any existing CA. Remediation: Verify the CA name and try again.
`400 Bad Request`	`VALIDATION_ERROR_0004`	A field contains an invalid value. For example, a non-numeric value was provided for `validityUnitValue`. Remediation: Provide valid input values.
`400 Bad Request`	`INVALID_TEMPLATE`	The specified template does not exist. Remediation: Verify the template name and try again.
`401 Unauthorized`	`AVX_GW_003`	Authentication failed — invalid credentials. Remediation: Provide a valid `username` and `password` or a valid `sessionId`.

Sample Request/Response

Sample Request

{
  "templateName": "RootCA_Default",
  "validityUnit": "years",
  "validityUnitValue": 5,
  "policyName": "DefaultPolicy",
  "csrParameters": {
    "commonName": "RootCA",
    "organization": "AppViewX Inc.",
    "organizationUnit": "Engineering",
    "locality": "Coimbatore",
    "state": "Tamil Nadu",
    "country": "IN"
  }
}

Sample Response

{
  "response": "Success",
  "message": "PKIaaS approval request initiated 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.