API v2: Listeners¶

Listener determines server connection mode (proxy, gateway, transparent, bastion) as well as its specifics.

Data structures¶

`ListenerModel`¶
Attribute	Type	Required	Description
id	string	yes	Read-only object Identifier
name	string	yes	Unique listener’s name
blocked	boolean; default value `false`	yes
reason	string	if `blocked` == `true`
announcement	string	no
ignore_case	boolean; default value `false`	If `protocol` == `vnc` \|\| `ssh`
legacy_crypto	boolean; default value `false`	If `protocol` == `ssh` \|\| `http` \|\| `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
mode	string {bastion, gateway, proxy, transparent}	yes	Case insensitive
listen_interface	string	If `mode` == `gateway` \|\| `transparent`	Network interface for user connections
listen_ip	string; default value `0.0.0.0`	If `mode` == `bastion` \|\| `proxy`	IP address for user connections
listen_port	number; value range from `1` to `60000`	If `mode` == `bastion` \|\| `proxy`	Port number for user connections
external_address	string	with `external_port`	Listener address to present in Access Gateway
external_port	number; value range from `1` to `65535`	with `external_address`	Listener port to present in Access Gateway
http_render	boolean; default value `true`	If `protocol` == `http`	Is graphical representation for HTTP(S) sessions enabled?
private_key_passphrase	string	with `rdp_private_key` or `ssh_private_key` or `tls_private_key`	Passphrase to use to decrypt private key.
rdp	ListenerRDPAttributes	If `protocol` == `rdp`	RDP protocol properties
ssh	ListenerSSHAttributes	If `protocol` == `ssh`	SSH protocol properties
tls	ListenerTLSAttributes	If `protocol` == `http` \|\| `rdp`	TLS protocol properties
created_at	datetime		Read-only
modified_at	datetime		Read-only
removed	boolean		Read-only
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.

`ListenerRDPAttributes`¶
Attribute	Type	Required	Description
rdp_private_key	string	If `protocol` == `rdp` & `tls_enabled` == `false`	RDP private key
rdp_public_key	string	If `protocol` == `rdp` & `tls_enabled` == `false`	RDP public key

`ListenerSSHAttributes`¶
Attribute	Type	Required	Description
ssh_private_key	string	yes	SSH private key
ssh_proxyjump	boolean; default value `false`	yes	Is SSH ProxyJump function enabled?
ssh_public_key	string	yes	Read-only SSH public key
ssh_fingerprint_sha256	string	If `protocol` == `ssh`	Read-only, expensive to use, SSH key SHA256 fingerprint

`ListenerTLSAttributes`¶
Attribute	Type	Required	Description
tls_enabled	boolean; default value `true`	If `protocol` == `http` \|\| `rdp`	Enabling the TLS protocol
tls_private_key	string	If `protocol` == `http` \|\| `rdp` & `tls_enabled` == `true`	TLS private key
tls_certificate	string	If `protocol` == `http` \|\| `rdp` & `tls_enabled` == `true`	TLS certificate
tls_certificate_commonname	string	If `protocol` == `http` \|\| `rdp` & `tls_enabled` == `true`	Read-only, expensive to use, TLS certificate `commonName`
tls_certificate_fingerprint_sha1	string	If `protocol` == `http` \|\| `rdp` & `tls_enabled` == `true`	Read-only, expensive to use, TLS certificate SHA1 fingerprint
tls_certificate_fingerprint_sha256	string	If `protocol` == `http` \|\| `rdp` & `tls_enabled` == `true`	Read-only, expensive to use, TLS certificate SHA256 fingerprint

Request for retrieving available attributes of the ListenerModel

Method	GET
Path	/api/v2/objspec/listener

`AccountSafeListenerAssignmentModel`¶
Attribute	Type	Required	Description
id	string	yes	Read-only object Identifier
account_id	string	yes	Immutable. Uniqueness is required in the combination of attribute `account_id` with attributes `safe_id` and `listener_id`.
safe_id	string	yes	Immutable. Uniqueness is required in the combination of attribute `safe_id` with attributes `account_id` and `listener_id`.
listener_id	string	no	Immutable. Uniqueness is required in the combination of attribute `listener_id` with attributes `account_id` and `safe_id`.
account_name	string		Read-only; expensive to use
account_type	string		Read-only; expensive to use
protocol	string		Read-only; expensive to use
server_id	string		Read-only; expensive to use; `null` if pool is assigned.
server_name	string		Read-only; expensive to use; `null` if pool is assigned.
pool_id	string		Read-only; expensive to use; `null` if server is assigned.
pool_name	string		Read-only; expensive to use; `null` if server is assigned.
safe_name	string		Read-only; expensive to use
listener_name	string		Read-only; expensive to use
created_at	datetime		Read-only
modified_at	datetime		Read-only
removed	boolean		Read-only
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.

Request for retrieving available attributes of the AccountSafeListenerAssignmentModel

Method	GET
Path	/api/v2/objspec/account_safe_listener

`ListenerGrantAssignmentModel`¶
Attribute	Type	Required	Description
id	string		Read-only, protected object Identifier
to_user_id	string	yes	Immutable. Expects unique `for_listener_id`
for_listener_id	string	yes	Immutable. Expects unique `to_user_id`
for_listener_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 ListenerGrantAssignmentModel

Method	GET
Path	/api/v2/objspec/listener_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 Listener objects.

Retrieving listeners list¶

Request

Method	GET
Path	/api/v2/listener

Example request

Sending GET https://10.0.0.0/api/v2/listener

    "result": "success",
"listener": [
    {
        "id": "1234138875067073217",
        "name": "rdp_list_fd_10647",
        "protocol": "rdp",
        "mode": "bastion",
        "listen_ip": "0.0.0.0",
        "listen_port": 3388,
        "blocked": false,
        "created_at": "2022-10-15 14:52:30.980597+02",
        "modified_at": "2022-10-15 14:52:30.980597+02",
        "legacy_crypto": false,
        "tls_enabled": true,
        "tls_certificate": "-----BEGIN CERTIFICATE-----\nMIIE0DCCArigAwIBAgIUSGWBY/C...0w/BXGR\n-----END CERTIFICATE-----"
    },
    {
        "id": "1234138875067073219",
        "name": "telnet_proxy_3",
        "protocol": "telnet",
        "mode": "proxy",
        "listen_ip": "0.0.0.0",
        "listen_port": 2236,
        "blocked": false,
        "created_at": "2022-10-17 09:34:32.582169+02",
        "modified_at": "2022-10-17 09:34:32.582169+02"
    },
    {
        "id": "12348875067073220",
        "name": "mssql_proxy",
        "protocol": "tds",
        "mode": "proxy",
        "listen_ip": "0.0.0.0",
        "listen_port": 8874,
        "blocked": false,
        "created_at": "2022-10-17 10:50:53.209773+02",
        "modified_at": "2022-10-17 10:50:53.209773+02" }]

Creating a listener¶

Request

Method	POST
Path	/api/v2/listener
Headers	Content-Type: Application/JSON
Body	ListenerModel

Retrieving a listener¶

Request

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

Modifying a listener¶

Request

Method	PATCH
Path	/api/v2/listener/<id>
Headers	Content-Type: Application/JSON
Body	ListenerModel

Example request: Changing the listener’s address

Sending PATCH https://10.0.0.0/api/v2/listener/12345678819172646915

{ "listen_ip": "10.0.2.0" }

Response

{ "result": "success" }

Retrieving users allowed to manage given listener¶

Request

Method	GET
Path	/api/v2/grant/listener

Granting management privileges¶

Request

Method	POST
Path	/api/v2/grant/listener
Body	{ to_user_id: 1234567890, for_listener_id: 1234567891 }

Creating an account-safe-listener assignments¶

Request

Method	POST
Path	/api/v2/account/safe/listener
Headers	Content-Type: Application/JSON
Body	AccountSafeListenerAssignmentModel

Example request

Sending POST https://10.0.0.0/api/v2/account/safe/listener

    { "account_id": 1232678819172646919,
"safe_id": 1232678819172646913,
"listener_id": 1232678819172646914 }

Response

    { "result": "success",
"account_safe_listener": {} }

Deleting an account-safe-listener assignment¶

Request

Method	DELETE
Path	/api/v2/account/<account_id>/safe/<safe_id>/listener/<listener_id>

Deleting a listener¶

Request

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