Add New Host

Before you begin

Before attempting to add a new host, the user has to ensure the following:

The host does not exist already.

Request Structure


Endpoint:	`/ssh/host/create`
Type:	`POST`
Sample URL:	`https://<IP/HostName/TenantName>:<GWPORT>/avxapi/ssh/host/create?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
Payload `Body`	(Mandatory) Contains all the parameters to be sent in the request body for the post request Type: Payload

Payload


Name	Description
data	(Mandatory) Contains request parameters to create and save the host. Type: Data

Table 2. **Data**
Name	Description
groupName	(Mandatory) Contains request parameters to create and save the host. Type: String
categoryType	(Mandatory) Category type of the host Type: String Possible Values: Server
vendorType	(Mandatory) Type of the vendor Type: String
ipAddress	(Mandatory) IP address of the host Type: String
fqdn	(Mandatory) Fully qualified domain name of the host Type: String
dataCenter	(Mandatory) Datacenter of the host Type: String
isClient	(Mandatory) Is the host client machine or not Type: Boolean
accessType	(Mandatory) Access type of the host Type: String Possible values: Key, Certificate
port	(Mandatory) Port number to connect to the host from Type: Number
deviceName	(Mandatory) Device name of the host Type: String
hostName	(Mandatory) Host name Type: String
loginType	(Mandatory) Login type for the host Type: String Possible values: Password, Identity Key
fileContent	(Mandatory) Identity Key file content, applicable only if “Identity Key” loginType is selected Content-Type: application/octet-stream
fileName	(Mandatory) Name of the Identity key file, applicable only if “Identity Key” loginType is selected Type: String
userName	(Mandatory) Username to login to the host Type: String
password	(Mandatory) Password to login to the host Type: String
isSudoUser	(Mandatory) Is sudo user or not Type: Boolean
credentialType	(Mandatory) Credential type for authentication to login to the host Type: String Possible values: Manual Entry, Credential List - AppViewX, Credential List - CyberArk, Credential List - Thycotic Secret
credentialName	(Mandatory) Credential name (null for “Manual Entry” credentialType) Type: String
accessGroups	(Mandatory) List of access groups where the host belongs to Type: List
userComplianceGroup	(Mandatory) User compliance group of the host Type: String
inventoryAction	(Mandatory) Inventory action for the host Type: String Possible values: Manage, Monitor, Do Not Move
accessElevation	(Mandatory) Access elevation of the user Type: String Possible Values: sudo, dzdo
sshSyncKeyDetail	(Mandatory) SSH sync key detail of the host Type: SshSyncKeyDetail

Table 3. SshSyncKeyDetails
Name	Description
sshScanType	(Mandatory) SSH scan type Type: String Possible values: Default, Full, Directory
sshScanDetails	(Mandatory) Details of SSH scan Type: List
discoverKeyType	(Mandatory) List of key types to be discovered Type: List
appInfraAccessGroup	(Mandatory) List of app infra access groups where the host belongs to Type: List

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 Type: response
message	Success message of the action or failure description in case of error. Will be non-null for failure response Type: String
appStatusCode	Application-specific status code for the response. Will be non-null for failure response Type: String
tags	More info in case of failure response

Response


response	Host created and saved successfully. Type: String

Status Codes

Table 5. Status Codes and Description
HTTP Status code	appStatusCode	Message and Possible remediation
200 OK	NA	Host created and saved successfully.
401 Unauthorized	AVX_GW_003	Authentication failed, reason - Invalid Credentials Possible remediation: Ensure that valid username and password or valid sessionId is provided as the header param.
400 Bad Request	AVX-VLDTN-001	Mandatory field is missing or invalid values specified - <<field name>> Possible remediation: Check and ensure that valid value is provided for <<field name>> field in the request.

Sample Request/Response

Use Case

To add new host using add_new_host API.

Request URL

https://<IP/HostName/TenantName>:<GWPORT>/avxapi/ssh/host/create?gwsource=external

Sample Request 1


{"data":
    {"groupName":"Default_Host_Group",
    "categoryType":"client",
    "vendorType":"linux",        
    "ipAddress":"1.1.1.1",
    "fqdn":"",    
    "dataCenter":"absecon",
    "isClient":false,
    "accessType":"Certificate",
    "port":"22",
    "deviceName":"test-device",
    "hostName":"",
    "loginType":"password",
    "userName":"appviewx",
    "isSudoUser":true,
    "credentialType":"Manual Entry",
    "credentialName":null,
    "accessGroupDeviceType":"Host",
    "accessGroups":["Default_Infra_Access_Group"],
    "userComplianceGroup":"Default_Key_Group",
    "clientServerAccessGroups":[],
    "sshSyncKeyDetail":{"sshScanType":"default","sshScanDetails":[],"discoverKeyType":["User Keys","Host Keys"],"appInfraAccessGroup":["Default_Infra_Access_Group"]},
    "inventoryAction":"manage","password":"dummy pwd","accessElevation":"sudo"}
}

Sample Request 2


{
    "fileContent": (binary),
    "fileName": "demo",
    "data":
    {"groupName":"Default_Host_Group",
    "categoryType":"client",
    "vendorType":"linux",
    "ipAddress":"1.1.1.1",
    "fqdn":"",
    "dataCenter":"absecon",
    "isClient":false,
    "accessType":"Certificate",
    "port":"22",
    "deviceName":"test-device",
    "hostName":"",
    "loginType":"file",
    "userName":"appviewx",
    "isSudoUser":true,
    "credentialType":"Manual Entry",
    "credentialName":null,
    "accessGroupDeviceType":"Host",
    "accessGroups":["Default_Infra_Access_Group"],
    "userComplianceGroup":"Default_Key_Group",
    "clientServerAccessGroups":[],
    "sshSyncKeyDetail":{"sshScanType":"default","sshScanDetails":[],"discoverKeyType":["User Keys","Host Keys"],"appInfraAccessGroup":["Default_Infra_Access_Group"]},
    "inventoryAction":"manage","password":"dummy pwd","accessElevation":"sudo"
}

Sample Response


{
   "response": "Host created and saved successfully.",
   "message": null,
   "appStatusCode": null,
   "tags": {},
   "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.