API v2: Servers

Server is a definition of the IT infrastructure resource, which can be accessed over one of the specified protocols.

Data Structures

ServerModel

Attribute	Type	Required	Description
id	string	yes	Unique, read-only object identifier. Requires read right on object type server for GET requests, modify for PATCH requests, and delete for DELETE requests.
name	string	yes	Unique server’s name.
description	string	no	Object description.
blocked	boolean; default value false	yes
reason	string	if blocked == true
bind_ip	string		Required format: IP address or fudo:label: <ip_label_name> for labeled IP addresses.
address	string	yes	IP address. Uniqueness is required in the combination of attribute address with attributes mask, port_first and port_last
mask	number {from 0 to 128}	no	Uniqueness is required in the combination of attribute mask with attributes address, port_first and port_last.
port_first	number		Value-format: port. Uniqueness is required in the combination of attribute port_first with attributes address, mask and port_last.
port_last	number		Value-format: port. Uniqueness is required in the combination of attribute port_last with attributes address, mask and port_first.
port	number	yes	Value-format: port. Read-write. Expensive to use. Port number used if no port range is defined. Uniqueness is required in the combination of attribute port with attributes address and mask.
legacy_crypto	boolean; default value false	If protocol == rdp || ssh || http || mysql || telnet || tn3270 || tn5250 || rdp & tls_enabled == true	Enabling legacy cryptographic protocols and settings.
protocol	string{http, modbus, mysql, rdp, ssh, system, tcp, tds, telnet, tn3270, tn5250, vnc}	yes	Immutable, case insensitive.
http	HTTPServerAttributes	If protocol == http	HTTP protocol properties.
mysql	MySQLServerAttributes	If protocol == mysql	MySQL protocol properties.
rdp	RDPServerAttributes	If protocol == rdp	RDP protocol properties.
tls	TLSServerAttributes	If tls_enabled == true	TLS protocol properties.
ssh_public_key	string	If protocol == ssh	SSH public key. Value format: ssh public key.
last_login	datetime		Read-only; Expensive to use.
pools	object-array		Read-only; Expensive to use; JSON object array containing id and name of assigned pools.
pools_ids	string-array		Read-only; hidden; expensive to use
pools_names	string-array		Read-only; hidden; expensive to use
state	string		Server’s discovery state: discovered, onboarded, quarantined or created (for manually created accounts). Read-only. Expensive to use.
discovered_at	datetime		Read-only. Expensive to use. Server discovered at timestamp.
onboarded_at	datetime		Read-only. Expensive to use. Server onboarded at timestamp.
onboarded_by_id	string		Read-only. Expensive to use. Unique identifier of the user who performed the onboarding.
onboarded_by_name	string		Read-only. Expensive to use. Name of the user who performed the onboarding.
quarantined_at	datetime		Read-only. Expensive to use. Server quarantined at timestamp.
quarantined_by_id	string		Read-only. Expensive to use. Unique identifier of the user who performed the quarantine.
quarantined_by_name	string		Read-only. Expensive to use. Name of the user who performed the quarantine.
scanner_id	string		Read-only. Expensive to use. Unique identifier of a scanner used to discover this server.
scanner_name	string		Read-only. Expensive to use. Name of a scanner used to discover this server.
rights	string-array		Read-only; list of rights the subject has to this object.
created_at	datetime		Read-only. Timestamp of creation.
modified_at	datetime		Read-only. Timestamp of modification.
builtin	boolean		Read-only; Expensive to use; If true, the object is not editable.
hidden	boolean		Read-only; Expensive to use; If true, the object is hidden in UI.

HTTPServerAttributes

Attribute	Type	Required	Description
http_host	string	yes	HTTP host header value.
http_timeout	number {seconds}	yes	Period of inactivity, after which the user will have to authenticate again.
http_authentication	boolean; default value false	no
http_authentication _method	string {Asana, Azure, Facebook, HPE BladeSystem, HPE iLO, HTTP Authentication, LinkedIn, Salesforce, Twitter}; Default value null	If http_authentication == true	Case insensitive.
http_username_element	string	If http_authentication == true & http_authentication_method == null	Custom login page details.
http_press_enter	boolean; default value false	If http_authentication == true & http_authentication_method == null	The Press the enter key prior to password option.
http_password_element	string	If http_authentication == true & http_authentication_method == null	Custom login page details.
http_signon_realm	string	If http_authentication == true & http_authentication_method == null	Custom login page details.

tabularcolumns::

p{0.27linewidth} p{0.16linewidth} p{0.31linewidth} p{0.15linewidth}

MySQLServerAttributes

Attribute	Type	Required	Description
mysql_tls_required	boolean; default value false	If protocol == mysql & tls_enabled == true

RDPServerAttributes

Attribute	Type	Required	Description
rdp_hotseat	boolean; default value false	If protocol == rdp	The option to have the users informed that other users are connected to the server, they are trying to connect to.
rdp_nla_enabled	boolean; default value true	If protocol == rdp & tls_enabled == true
rdp_public_key	string	If protocol == rdp & tls_enabled == false	RDP public key. Value format: public-key.

TLSServerAttributes

Attribute	Type	Required	Description
tls_enabled	boolean; default value true	If protocol == rdp || http || mysql || telnet || tn3270 || tn5250	Enabling the TLS protocol.
tls_ca_certificate	string	If protocol == rdp || http || mysql || telnet || tn3270 || tn5250 & tls_enabled == true	TLS CA certificate. Value format: x509-certificate
tls_certificate	string	If protocol == rdp || http || mysql || telnet || tn3270 || tn5250 & tls_enabled == true	TLS certificate. Value format: x509-certificate

Retrieve Available Attributes of the ServerModel

Request

Method	GET
Path	/api/v2/objspec/server

To check allowed methods, available URL parameters and possible responses please refer to the API Overview section.

Refer to the Batch operations topic to create nested requests for operating on the Server objects.

Create a Server

Request

Method	POST
Path	/api/v2/server
Headers	Content-Type: Application/json
Body	ServerModel

Example Request

POST /api/v2/server

      {
"name": "my-1st-rdp-server",
"protocol": "rdp",
"address": "10.0.2.0",
"port": 3389,
"legacy_crypto": false
      }

Response

    { "result": "success",
"server": {
    "id": "41234678819172646916" }}

Get Servers List

Request

Method	GET
Path	/api/v2/server

Get a Server

Request

Method	GET
Path	/api/v2/server/<id>

Example Request

GET /api/v2/server/<id>

    {
"result": "success",
"server": {
    "id": "4602678819172646916",
    "name": "my-1st-rdp-server",
    "blocked": false,
    "address": "10.0.2.0",
    "mask": 32,
    "port": 3389,
    "protocol": "rdp",
    "legacy_crypto": false,
    "rdp_hotseat": false,
    "rdp_nla_enabled": true,
    "tls_enabled": true,
    "tls_use_ca_store": false,
    "created_at": "2022-10-27 01:43:39.688273-07",
    "modified_at": "2022-10-27 01:43:39.688273-07",
    "last_login": "-infinity"
}}

Modify a Server

Request

Method	PATCH
Path	/api/v2/server/<id>
Headers	Content-Type: Application/json
Body	ServerModel

Example Request: Enable Using CA Store for Server Verification

PATCH /api/v2/server/<id>

{"tls_use_ca_store": true}

Response

{ "result": "success" }

Deleting a Server

Request

Method	DELETE
Path	/api/v2/server/<id>