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

Request for Retrieving Available Attributes of the ServerModel

Method 
GET
Path 
/api/v2/objspec/server
ServerPoolModel
Attribute Type Required Description
id number yes Read-only object Identifier.
pool_id number yes Immutable. Uniqueness is required in the combination of attribute pool_id with attribute server_id.
server_id number yes Immutable. Uniqueness is required in the combination of attribute server_id with attribute pool_id.
created_at datetime   Read-only.
modified_at datetime   Read-only.
removed boolean   Read-only.

Request for Retrieving Available Attributes of the ServerPoolModel

Method 
GET
Path 
/api/v2/objspec/pool_server

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

The next chapter describes procedures for creating separate requests.

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


Creating a Server

Request

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

Example Request

Sending POST https://10.0.0.0/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" }}

Retrieving Servers List

Request

Method 
GET
Path 
/api/v2/server

Retrieving a Server

Request

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

Example Request

Sending GET https://10.0.0.0/api/v2/server/41234678819172646916

    {
"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"
}}

Modifying 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

Sending PATCH https://10.0.0.0/api/v2/server/41234678819172646916

{"tls_use_ca_store": true}

Response

{ "result": "success" }

Adding a Server to the Pool

Request

Method 
POST
Path 
/api/v2/pool/server
Headers 
Content-Type: Application/JSON
Body 
ServerPoolModel

Example Request

Sending POST https://10.0.0.0/api/v2/pool/server

     { "pool_id": "122678819172646916",
"server_id": "123402678819172646914"}

Response

    { "result": "success",
"pool_server": {} }

Deleting a Server From a Pool

Request

Method 
DELETE
Path 
/api/v2/pool/<pool_id>/server/<server_id>

Deleting a Server

Request

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