User Key/Certificate Provision

The API will provision the key to the provided host(s) and vault. The endpoint to also support SSH certificate provisioning using certProvision flag and a certificateConfiguration object. The system documents the complete API contract in swaggerAPIs.json.

Before you begin

Before attempting to provision the key, make sure the current key groups of the provided key and the Infra Access Group associated host(s) have RW permissions.

Request Structure


Endpoint:	`/ssh/user-key/provision`
Type:	`POST`
Sample URL:	`https://<IP/HostName/TenantName>:<GWPORT>/avxapi/ssh/user-key/provision?gwsource=external` To understand the elements of the sample URL, click here.
Headers:
Content-Type:	application/json

Table 1. Request Parameters
Name	Description
sessionId `Header`	(Mandatory) Session ID received after login. Type: String Constraints: Required if username and password are not provided.
username `Header`	(Mandatory) AppViewX login username. Type: String Constraints: Required if sessionId is not provided.
password `Header`	(Mandatory) AppViewX login password. Type: String Constraints: Required if sessionId is not provided.
Content-Type `Header`	(Mandatory) Specifies the nature of the data in the payload. Type: String Constraints: The value of the param should be ‘application/json’.
gwsource `Query`	(Mandatory) Source from which the request is triggered. (E.g. external) Type: String
requestId `queryParam`	(Mandatory) Request Id of the bulk upload request. Type: String
Payload `Body`	(Mandatory) Contains all the parameters to be sent in the request body for the post request. Type: Payload

Payload


Name	Description
keyFingerPrint	(Mandatory) Fingerprint of the provided SSH key (base64-encoded SHA256). Type: String
enableVaultConfig	Flag to enable/disable the vault-managed key configuration. Type: Boolean Possible values: true, false (default: false)
certProvision	Determines which `keyEntity` values are valid. Set to true to generate and provision a signed SSH certificate. Type: Boolean Possible values: true, false (default: false)
infraAccessGroupName	(Mandatory only when certProvision=true). The IAG that all target hosts must belong to. Type: String Possible values: Infra Access Groups that are managed in AppViewX
keyProvisionRequestDetails[]	(Mandatory) Request details to provision key to the Infra Access Group associated host(s). Type: KeyProvisionRequestDetails
certificateConfiguration	(Mandatory when certProvision=true) Contains the SSH certificate signing parameters. Type: CertificateConfiguration

Table 2. KeyProvisionRequestDetails
Name	Description
deviceName	Hostname or IP of the managed device. Type: String
filePath	Absolute path on the device where the key file is written. Type: String
userName	(Mandatory) OS username on the target device. Acts as the allowed principal entry in the `authorized_principals` file on the target host. Type: String
keyEntity	(Mandatory) When certProvision=false: `"privateKey"` (user private key for user trust) or `"publicKey"` (user private key for user trust). certProvision=true: `"serverIdentityAndTrust"` (provisions host key, host certificate, authorized principals, and user CA trust on the server) or `"clientIdentityAndTrust"` (configures host CA trust in known_hosts and user certificate on the client). Type: String

Table 3. CertificateConfiguration
Name	Description
certKeyId	(Mandatory in the certConfig) Key ID / comment embedded in the signed certificate. Type: String
principals	(Mandatory in the certConfig) OS usernames or roles the certificate grants access for. Type: String[]
validFrom	(Mandatory in the certConfig) Certificate validity start — Unix timestamp in milliseconds. Type: Long
validTo	(Mandatory in the certConfig) Certificate validity end — Unix timestamp in milliseconds. Type: Long
extensions	SSH certificate extensions to include. Must be a subset of the group policy allowed list. Type: String[] Permitted values: permit-agent-forwarding, permit-port-forwarding, permit-pty, permit-user-rc, and permit-X11-forwarding
sourceIps	Comma-separated CIDR/IP restrictions. Omit for unrestricted certificate-based access. Type: String
forceCommands	Comma-separated forced commands. Omit for unrestricted certificate-based access. Type: String

Response Structure

200 OK returns string of type application/json with the following body params.

Table 4. Response Parameters
Name	Description
response	Contains the response message of the API. Type: Key provision response
message	null Type: String
appStatusCode	null. Type: String
tags	More info in case of failure response.

Table 5. Key provision response
Name	Description
status	Status of the key provision request. Type: String

Status Codes

Table 6. Status Codes and Description
HTTP Status code	appStatusCode	Error Message, Cause, and Remediation
200 OK	NA	Success
400 Bad Request	VALIDATION_ERROR_0004	Invalid 'keyFingerPrint'. Cause: The provided fingerprint value fails format validation. Possible remediation: Supply a valid base64-encoded SHA256 fingerprint.
400 Bad Request	VALIDATION_ERROR_0004	Mandatory Field 'keyFingerPrint' is missing or empty. Cause: `keyFingerPrint` field absent or blank in the request. Possible remediation: Include a non-empty `keyFingerPrint` in the payload.
400 Bad Request	ERR-SSH-NB-300	One or more hosts do not have permission to perform this action. Cause: One or more endpoints in `keyProvisionRequestDetails` does not have the required ACL permission. Possible remediation: Verify that the target hosts have the necessary SSH permissions configured.
400 Bad Request	SSH-PROVISION-KEY-012	Invalid certificate provisioning configuration.::[Missing certificate configuration for cert provisioning]. Cause: `certProvision=true` but `certificateConfiguration` is absent. Possible remediation: Include a fully populated `certificateConfiguration` object.
400 Bad Request	SSH-PROVISION-KEY-012	Invalid certificate provisioning configuration.::[Invalid certificate validity period]. Cause: `validTo <= validFrom` in `certificateConfiguration`. Possible remediation: Provide a `validTo` timestamp strictly greater than `validFrom`.
400 Bad Request	SSH-PROVISION-KEY-012	Invalid certificate provisioning configuration.::[Non-Linux host for cert provisioning]. Cause: Target host is not a Linux host; cert provisioning only supports Linux. Possible remediation: Use only Linux endpoints for cert provisioning.
400 Bad Request	SSH-PROVISION-KEY-012	Invalid certificate provisioning configuration.::[Missing user CA in access group]. Cause: The specified Infrastructure Access Group has no user CA configured. Possible remediation: Configure a user CA in the IAG before submitting a cert provisioning request.
400 Bad Request	SSH-PROVISION-KEY-014	Certificate provisioning policy not found for the key group. Cause: No requestor policy with certificate configurations exists for the key's group. Possible remediation: Create or update the requestor policy for the key group.
400 Bad Request	SSH-PROVISION-KEY-015	Requested extensions are not allowed by the policy.::[No extensions allowed by policy]. Cause: One or more requested extensions are not in the policy's allowed list. Possible remediation: Only request extensions permitted by the group policy.
400 Bad Request	SSH-PROVISION-KEY-016	Requested certificate validity exceeds the maximum allowed by the policy.::[Certificate validity exceeds policy limit]. Cause: `validTo - validFrom` exceeds the policy's `maxValidityDuration`. Possible remediation: Reduce the validity period to stay within the policy limit.
400 Bad Request	SSH-PROVISION-KEY-017	Host is not in Managed status. Certificate provisioning requires managed hosts.::[Host not managed for cert provisioning]. Cause: Host status is not "Managed". Possible remediation: Ensure the host is fully onboarded to "Managed" status before provisioning.
400 Bad Request	SSH-PROVISION-KEY-018	At least one endpoint is required when certificate provisioning is enabled. Cause: `certProvision=true` but `keyProvisionRequestDetails` is null or empty. Possible remediation: Include at least one endpoint.
400 Bad Request	SSH-PROVISION-KEY-019	Host does not belong to the selected Infrastructure Access Group.::[Host not in selected IAG for cert provisioning]. Cause: Host's `accessGroups` does not include the specified `infraAccessGroupName`. Possible remediation: Add the host to the IAG or select the correct IAG.
400 Bad Request	SSH-PROVISION-KEY-020	Duplicate endpoint entries found in the request. Cause: Multiple entries share the same `deviceName`. Possible remediation: Remove duplicate device entries.
401 Unauthorized	AVX_GW_003	Authentication failed, reason - Invalid Credentials. Cause: Missing or invalid session token.
404 Not Found	ERR-SSH-NB-264	Key not found::[SSH Key not available for the given finger print]. Cause: No SSH key found in inventory matching the given `keyFingerPrint`. Possible remediation: Verify the fingerprint value and ensure the key exists in the SSH inventory.
404 Not Found	AVX_GW_009	Resource not found, reason - Invalid apiid. Cause: The action ID `ssh-key-provision` is not registered with the API Gateway. Possible remediation: Ensure the SSH subsystem is deployed and the action is registered.
417 Expectation Failed	SSH-PROVISION-KEY-013	Failed to generate SSH certificate.::[Error during SSH certificate signing]. Cause: CA signing service error — CA unreachable, key format issue, or signing failure. Possible remediation: Verify the CA is online and the public key format is compatible. Check server logs.
417 Expectation Failed	ERR-ORCHESTRATOR-NB-004	Error in sending workflow request task. Cause: The orchestrator failed to submit the workflow task after the request was persisted. Possible remediation: Check orchestrator connectivity and logs. The request is saved in INITIATED status and will be retried by the cron task.

Sample Request/Response

Use Case

To provision the key to the Infra Access Group associated host(s) and vault using /user-key/provision API.

Request URL

https://<IP/HostName/TenantName>:<GWPORT>/avxapi/ssh/user-key/provision?gwsource=external

Sample Request

{
  "keyFingerPrint": "Abr8U7wSxFe7/R3OQ6fBOUw4TRGI6bnwkJO3Hit05WI",
  "enableVaultConfig": false,
  "certProvision": true,
  "infraAccessGroupName": "Default_Infra_Access_Group",
  "keyProvisionRequestDetails": [
    {
      "deviceName": "host-01.example.com",
      "filePath": "/home/appuser/.ssh/id_rsa",
      "userName": "appuser",
      "keyEntity": "clientIdentityAndTrust"
    },
    {
      "deviceName": "host-02.example.com",
      "keyEntity": "serverIdentityAndTrust"
    }
  ],
  "certificateConfiguration": {
    "certKeyId": "appuser-host01-20260318",
    "principals": ["appuser", "root"],
    "validFrom": 1852284800000,
    "validTo": 1852285800000,
    "extensions": [
      "permit-pty",
      "permit-agent-forwarding",
      "permit-port-forwarding"
    ],
    "sourceIps": "10.0.1.0/24,192.168.1.100",
    "forceCommands": "/usr/bin/restricted-shell,/opt/scripts/deploy.sh"
  }
}

Sample Response

{
  "response": {
    "status": "Key provision request saved Successfully"
  },
  "message": null,
  "appStatusCode": null,
  "tags": null,
  "headers": null
}

Reference

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.
Note: GWPORT is not required for SaaS setups.
Example: 31443
avxapi: Path parameter value (static) that is part of the endpoint's URL
Endpoint: Endpoint of the API, for example: /ssh/host/create
gwsource: Source or origin of a gateway, for example: external.

What's Next

Create Key