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.
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 and port.
mask number {from 0 to 128} no Uniqueness is required in the combination of attribute mask with attributes address and port.
port number {from 1 to 65535} yes 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 || telnet || tn3270 || tn5250 & 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.
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.
created_at datetime   Read-only.
modified_at datetime   Read-only.
removed boolean   Read-only.
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.
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.
RDPServerAttributes
Attribute Type Required Description
rdp_hotseat boolean; default value false yes 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.
TLSServerAttributes
Attribute Type Required Description
tls_enabled boolean; default value true If protocol == rdp || http || telnet || tn3270 || tn5250 Enabling the TLS protocol.
tls_ca_certificate string If protocol == rdp || http || telnet || tn3270 || tn5250 & tls_enabled == true TLS CA certificate.
tls_certificate string If protocol == rdp || http || telnet || tn3270 || tn5250 & tls_enabled == true TLS 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
ServerGrantAssignmentModel
Attribute Type Required Description
id string   Read-only, protected object Identifier
to_user_id string yes Immutable. Expects unique for_server_id
for_server_id string yes Immutable. Expects unique to_user_id
for_server_name string   Read-only, expensive to use
to_user_name string   Read-only, expensive to use
to_user_role string   Read-only, expensive to use
created_at string   Read-only
modified_at string   Read-only
removed boolean   Read-only

Request for Retrieving Available Attributes of the ServerGrantAssignmentModel

Method 
GET
Path 
/api/v2/objspec/server_grant

Note

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>

Retrieving Users Allowed to Manage Servers

Request

Method 
GET
Path 
/api/v2/grant/server

Example Request

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

Response

    { "result": "success",
"server_grant": [
    {
        "for_server_id": "4602678819172646916",
        "to_user_id": "4602678819172646914",
        "created_at": "2022-10-27 01:51:15.839452-07",
        "modified_at": "2022-10-27 01:51:15.839452-07" }]}

Granting Management Privileges

Request

Method 
POST
Path 
/api/v2/grant/server
Body 
        {
to_user_id: 1234567890,
for_server_id: 1234567891
}

Deleting a Server

Request

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