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

Deprecated since version 5.5

Please note that the endpoints described in this subsection have been deprecated and are scheduled for removal in the next major release.

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¶

Deprecated since version 5.5

Please note that the endpoints described in this subsection have been deprecated and are scheduled for removal in the next major release.

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¶

Deprecated since version 5.5

Please note that the endpoints described in this subsection have been deprecated and are scheduled for removal in the next major release.

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>