Client scripting API

The BeyondTrust Representative Console Scripting feature is composed of three parts:

The BeyondTrust Representative Console Script file format
New and deprecated command line parameters for the representative console
The BeyondTrust client scripting API

The BeyondTrust representative console script file

A BeyondTrust Representative Console Script (BRCS) is a file that contains a sequence of commands to be executed by the BeyondTrust representative console. The file extension is in the format "brcs-<companySiteName>" (Company Site Name is the name used to access your support site). During installation the BeyondTrust representative console will use the OS to associate the representative console with the BRCS file type. Therefore users can double-click a BRCS file and have it automatically executed by the BeyondTrust representative console.

BRCS files have the following format:

BRCS1.0
<command>
<command>
…

This is more formally expressed as:

brcs_file = header , newline , commands ;
header = "BRCS" , version ;
version = digit , "." , digit ;
commands = command { newline , command } ;
digit = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" ;
newline = "\n" | "\r\n" ;

ℹ️
Note
Note that script files can have a maximum of 10 commands.

Each command consists of a set of key-value pairs separated by "&". The key in each pair is separated from the value by "=". Keys and values use the percent-encoding algorithm described in RFC3986 section 2.1. This is commonly referred to as url-encoding or url-escaping. It is commonly seen in the address bar of web browsers to represent the parameters passed to a web server. Commands have the following format:

action=<action>&parameter1=value1&parameter2=value2...

This is more formally expressed as:

command = "action=", value, [ parameters ] ;
parameters =  "&", parameter, [ parameters ] ;
parameter = url_encoded_string, "=", url_encoded_string ;
url_encoded_string = {* see RFC 3986 *} ;

Command line parameters for the representative console

Two command line parameters have been added to the representative console to support BRCS:

run-script <BRCS command>
run-script-file <path to BRCS file>

These command line parameters allow customers to implement BRCS login via the command line. These two new parameters overlap with two existing parameters. Therefore, the "-jump" and "-push" command line parameters are now deprecated and will be removed in a future release.

Old Command Line	New Command Line
push<hostname>	run-script "action=push_and_start_local&hostname=<hostname>"
jump<search string>	run-script "action=start_pinned_client_session&search_string=<search_string>"

Different behaviors can be seen when running a script from the command line depending on the state of the representative console:

If the representative console is not running, then attempting to run a script from the command line causes the representative console to start the login dialog. After the representative successfully logs in, the script is run.
If the representative console is already running, but the representative is not logged in, then the login dialog is shown. After the representative logs in, the script is run.
If the representative console is already running and the representative is already logged in, then attempting to run a script from the command line causes the existing instance of the representative console to run the script.

Representative console exit status:

If an invalid script is given on the command line, then the representative console will terminate with an exit status > 0.
If a valid script is given on the command line, then the representative console will terminate with an exit status of 0.

Examples:

bomgar-rep.exe --run-script "action=generate_session_key&session.custom.external_key=123456789"
bomgar-rep.exe --run-script-file my_script_file.brcs-beta60

The BeyondTrust client scripting API

The client scripting API enables you to generate a BeyondTrust Representative Console Scripting (BRCS) file which allows you to send commands to the BeyondTrust representative console from external applications.

Customers can use the client scripting API to generate BRCS files that can start a support session with a specific Jump Client, push and start a session with a Windows system within a local network, prompt representatives to generate a session key, start a vPro session with a specified system, or to simply log in to the representative console.

The client scripting API URL is https://support.example.com/api/client_script.

This API accepts a client type (rep), an operation to perform (generate), a command to put in the script file, and a set of parameters to pass to the command. Here is an example of a valid Client Scripting API request:

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_pinned_client_session&search_string=ABCDEFG02

The above request will prompt the user to download a BeyondTrust representative console script file. After downloading the script file, the user can run it using the representative console. In this case, the script file will contain commands to start a session with the Jump Client whose hostname, comments, public IP, or private IP matches the search string "ABCDEFG02".

Parameters for client scripting API


type=rep type=web_console	The BeyondTrust client to which the command applies. Currently the API only supports rep or web_console as the client type.
operation=generate operation=execute	The operation to perform. Currently the API only supports generate and execute as the operation. If the type is rep, the operation should be generate. If the type is web_console, the operation should be execute.
action=<command> or action=<command>&parameter=[value]	The name of the command to run. Most commands have required and/or optional parameters. The type web_console supports only the generate_session_key and start_jump_item_session actions.

Commands

login

When generating any BeyondTrust Representative Console Script, the login command is automatically added as the first command in the script file. It does not need to be specified in the URL used to generate the script file.

By default, this command opens the representative console and attempts to log in using the credentials saved locally in the representative console. If no credentials are saved, the command simply opens the representative console login prompt. Once the representative has correctly authenticated, the script continues running.

The login command has no effect if a representative is already logged into the representative console.

If you wish to specify the credentials to be used, you can create a separate script specifically to be used for logging in. The login command passes the login mechanism along with a username and password. Both username and password parameters are sent in plain text, unencrypted.

⚠️
Important
You cannot specify multiple commands in the URL used to generate a script. For example, you cannot specify login and an action such as generate_session_key in the same URL. Each command must be generated as a separate script.
However, a skilled developer may edit the .brcs script file once it has been generated in order to modify the login credentials and then run another command. BeyondTrust does not support scripts modified in this manner.

Optional parameters for login


mechanism=[string]	The mechanism to use for authentication. Currently, only username_password is supported. If this parameter is supplied, both other parameters must also be supplied.
username=[string]	The username of the account with which to log in. If this parameter is supplied, both other parameters must also be supplied.
password=[string]	The password of the account with which to log in. If this parameter is supplied, both other parameters must also be supplied.

Query examples: login

https://support.example.com/api/client_script?type=rep&operation=generate&action=login&mechanism=username_password&username=username&password=password

generate_session_key

In the context of the client scripting API, the generate_session_key command causes the representative console to show the Generate Session Key dialog. Parameters can be passed to the command to customize the behavior.

Optional parameters for the generate_session_key command


public_portal_hostname=[string]	The hostname of the public portal that should be selected by default when the Generate Session Key dialog is shown. The representative will still have the option to change the public portal on the dialog. This field has a maximum length of 255 characters.
session.custom.[custom field]=[string]	The code name and value of any custom fields. These fields must first be configured in /login > Management > API Configuration. Each attribute must be specified as a different parameter. Each custom field has a maximum length of 1024 characters. The maximum total size of all combined custom fields, including the external key, must be limited to 10KB.

ℹ️
Note
Parameters are optional for the generate_session_key command. Omitting them will simply cause the representative console to show the Generate Session Key dialog.

Query examples: generate_session_key

Show the Generate Session Key dialog

https://support.example.com/api/client_script?type=rep&operation=generate&action=generate_session_key

Show the Generate Session Key dialog with the public portal hostname "support.example.com" selected

https://support.example.com/api/client_script?type=rep&operation=generate&action=generate_session_key&public_portal_hostname=support.example.com

Show the Generate Session Key dialog and associate custom attributes with any support sessions started using the session key or URL shown on the dialog

https://support.example.com/api/client_script?type=rep&operation=generate&action=generate_session_key&session.custom.custom_field1=Custom%20Value&session.custom.custom_field2=123

push_and_start_local

The push_and_start_local command attempts to push the customer client to a computer on the local network to start a support session. This can also be described as a local Jump.

Required parameter for push_and_start_local


hostname=[string]	The hostname of the computer that is the target of the push and start operation. This field has a maximum length of 255 characters.

Optional parameter for push_and_start_local


session.custom.[custom field]=[string]	The code name and value of any custom fields. These fields must first be configured in /login > Management > API Configuration. Each attribute must be specified as a different parameter. Each custom field has a maximum length of 1024 characters. The maximum total size of all combined custom fields, including the external key, must be limited to 10KB.

Query examples: push_and_start_local

Jump to the local network computer "ABCDEF02"

https://support.example.com/api/client_script?type=rep&operation=generate&action=push_and_start_local&hostname=ABCDEF02

Jump to the local network computer "ABCDEF02" and associate custom attributes with the session

https://support.example.com/api/client_script?type=rep&operation=generate&action=push_and_start_local&hostname=ABCDEF02&session.custom.custom_field1=Custom%20Value&session.custom.custom_field2=123

push_and_start_remote

The push_and_start_remote command attempts to push the customer client to a computer on a remote network through a Jumpoint in order to start a support session. This can also be described as a remote Jump.

Required parameter for push_and_start_remote


target=[string]	The hostname or IP address of the target machine.

Optional parameters for push_and_start_remote


jumpoint=[string]	The Jumpoint through which to start the session. This Jumpoint must be on the same subnet as the target computer. If not specified and the user has access to only one Jumpoint, then that Jumpoint is used automatically. If not specified and the user has access to more than one Jumpoint, then a dialog will open from which the user must select a Jumpoint.
session.custom.[custom field]=[string]	The code name and value of any custom fields. These fields must first be configured in /login > Management > API Configuration. Each attribute must be specified as a different parameter. Each custom field has a maximum length of 1024 characters. The maximum total size of all combined custom fields, including the external key, must be limited to 10KB.

start_jump_item_session

The start_jump_item_session command attempts to start a session with a BeyondTrust Jump Item. Users may run this command for all Jump Items they are permitted to access via the Jump management interface in the representative console.

Optional parameters for the start_jump_item_session command


credential_id	If specified, only a Jump Item with that specific credential ID associated is returned. This field has a maximum length of 255 characters.
jump.method	If specified, only Jump Items using the designated Jump method are included in the results. Acceptable values for this field are push (remote push), local_push, pinned (Jump Client), rdp, vnc, and shelljump.
search_string	Identifies the search criteria used to select and return specific Jump Items as results. This parameter is required only if no of the client fields below are specified.
client.comments	If specified, only Jump Items with the given comments are included in the results. This field has a maximum length of 255 characters. Search is partial and case-insensitive.
client.hostname	If specified, only Jump Items with the given hostname are included in the results. This field has a maximum length of 255 characters. Search is partial and case-insensitive.
client.private_ip	If specified, only Jump Clients with the given private IP address are included in the results. This search field applies only to Jump Clients. This field has a maximum length of 255 characters. Search is partial and case-insensitive.
client.public_ip	If specified, only Jump Clients with the given public IP address are included in the results. This search field applies only to Jump Clients. This field has a maximum length of 255 characters. Search is partial and case-insensitive.
client.tag	If specified, only Jump Items with the given tag are included in the results. This field has a maximum length of 255 characters. Search is partial and case-insensitive.
session.custom.[custom field]=[string]	The code name and value of any custom fields. These fields must first be configured in /login > Management > API Configuration. Each attribute must be specified as a different parameter. Each custom field has a maximum length of 1024 characters. The maximum total size of all combined custom fields, including the external key, must be limited to 10KB.

⚠️
Important
At least one client.* parameter must be specified. If multiple client.* parameters are specified, then only clients matching all criteria are returned.

Query examples: start_jump_item_session

Start a session with a Jump Item whose hostname contains "ABCDEF02"

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_jump_item_session&client.hostname=ABCDEF02

Start a session with a Jump Item whose comments contain "maintenance" and whose tag contains "server"

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_jump_item_session&client.comments=maintenance&client.tag=server

Start a session with a pinned Jump Client whose private IP address begins with "10.10.24" and associate custom attributes with the session

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_jump_item_session&client.private_ip=10.10.24&jump.method=pinned&session.custom.custom_field1=Custom%20Value&session.custom.custom_field2=123

ℹ️
Note
If more than one Jump Item matches the search criteria, then a dialog opens, giving the user the option to select the appropriate Jump Item.

start_rdp_session

The start_rdp_session command initiates a Microsoft Remote Desktop Protocol session on the target machine using a Jumpoint.

Required parameter for the start_rdp_session command


target=[string]	The hostname or IP address of the machine targeted for an RDP session.

Optional parameters for the start_rdp_session command


jumpoint=[string]	The Jumpoint through which to start the RDP session. This Jumpoint must be on the same subnet as the target computer. If not specified and the user has access to only one Jumpoint, then that Jumpoint is used automatically. If not specified and the user has access to more than one Jumpoint, then a dialog will open from which the user must select a Jumpoint.
username=[string]	The username to use when authenticating. If not specified, the representative must enter the username.
display_size=[string]	May be one of primary_display (default), all_displays, or <width>x<height>, where <width> and <height> are integers representing a standard resolution.
quality=[string]	May be one of low, performance (default), performance_quality, or quality.
console=[string]	Either no (default) or yes. If yes, the RDP session connects to the physical console.
session.custom.[custom field]=[string]	The code name and value of any custom fields. These fields must first be configured in /login > Management > API Configuration. Each attribute must be specified as a different parameter. Each custom field has a maximum length of 1024 characters. The maximum total size of all combined custom fields, including the external key, must be limited to 10KB.

Query examples: start_rdp_session

Start an RDP session with the computer "ABCDEF02"

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_rdp_session&target=ABCDEF02

Start an RDP session with the computer "ABCDEF02" through the Jumpoint "Network01"

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_rdp_session&target=ABCDEF02&jumpoint=Network01

Start an RDP session with the computer "ABCDEF02" through the Jumpoint "Network01". Authenticate with "jsmith", set the resolution to 1024x768, set the quality to "quality", and create a console session

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_rdp_session&target=ABCDEF02&jumpoint=Network01&username=jsmith&display_size=1024x768&quality=quality&console=yes

start_shell_jump_session

The start_shell_jump_session command initiates a Shell Jump session, creating an SSH or Telnet connection to a remote network device.

Required parameter for the start_shell_jump_session command


target=[string]	The hostname or IP address of the machine targeted for a Shell Jump session.

Optional parameters for the start_shell_jump_session command


jumpoint=[string]	The Jumpoint through which to start the Shell Jump session. This Jumpoint must be on the same subnet as the target computer. If not specified and the user has access to only one Jumpoint, then that Jumpoint is used automatically. If not specified and the user has access to more than one Jumpoint, then a dialog will open from which the user must select a Jumpoint.
username=[string]	The username to use when authenticating. If not specified, the representative must enter the username.
protocol=[string]	The network protocol to use. May be one of ssh (default) or telnet.
port=[integer]	The port number on which to connect. Defaults to 22.
terminal	The terminal type to use. May be one of xterm (default) or vt100.
session.custom.[custom field]=[string]	The code name and value of any custom fields. These fields must first be configured in /login > Management > API Configuration. Each attribute must be specified as a different parameter. Each custom field has a maximum length of 1024 characters. The maximum total size of all combined custom fields, including the external key, must be limited to 10KB.

Query examples: start_shell_jump_session

Start a Shell Jump session with the computer "ABCDEF02"

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_shell_jump_session&target=ABCDEF02

Start a Shell Jump session with the computer "ABCDEF02" through the Jumpoint "Network01"

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_shell_jump_session&target=ABCDEF02&jumpoint=Network01

Start a Shell Jump session with the computer "ABCDEF02" through the Jumpoint "Network01". Authenticate with "jsmith", and use a Telnet protocol through port 40 with terminal type vt100

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_shell_jump_session&target=ABCDEF02&jumpoint=Network01&username=jsmith&protocol=telnet&port=40&terminal=vt100

Start a Shell Jump session with the computer "ABCDEF02" and associate custom attributes with the session

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_shell_jump_session&target=ABCDEF02&session.custom.custom_field1=Custom%20Value&session.custom.custom_field2=123

start_vnc_session

The start_vnc_session command initiates a VNC session on the target machine using a Jumpoint.

Required parameter for the start_vnc_session command


target=[string]	The hostname or IP address of the machine targeted for a VNC session.

Optional parameters for the start_vnc_session command


jumpoint=[string]	The Jumpoint through which to start the VNC session. This Jumpoint must be on the same subnet as the target computer. If not specified and the user has access to only one Jumpoint, then that Jumpoint is used automatically. If not specified and the user has access to more than one Jumpoint, then a dialog opens from which the user must select a Jumpoint.
port=[integer]	The port number on which to connect. Defaults to 5900.
session.custom.[custom field]=[string]	The code name and value of any custom fields. These fields must first be configured in /login > Management > API Configuration. Each attribute must be specified as a different parameter. Each custom field has a maximum length of 1024 characters. The maximum total size of all combined custom fields, including the external key, must be limited to 10KB.

Query examples: start_vnc_session

Start a VNC session with the computer "ABCDEF02"

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_vnc_session&target=ABCDEF02

Start a VNC session with the computer "ABCDEF02" through the Jumpoint "Network01"

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_vnc_session&target=ABCDEF02&jumpoint=Network01

Start a VNC session with the computer "ABCDEF02" and associate custom attributes with the session

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_vnc_session&target=ABCDEF02&session.custom.custom_field1=Custom%20Value&session.custom.custom_field2=123

start_vpro_session

The start_vpro_session command initiates a vPro session on the target machine using the specified Jumpoint.

Required parameters for the start_vpro_session command


jumpoint=[string]	The Jumpoint through which to start the vPro session. This Jumpoint must be on the same subnet as the target computer and must be configured for vPro support.
target=[string]	The hostname or IP address of the machine targeted for a vPro session

ℹ️
Note
To initiate a vPro session using BeyondTrust Client Scripting, you must specify the target machine's hostname or private IP. (If Kerberos is used for vPro authentication, then the fully qualified domain name must be specified.) The Jumpoint name must also be specified. See the query examples below.

Optional parameter for the start_vpro_session command

	.
session.custom.[custom field]=[string]	The code name and value of any custom fields. These fields must first be configured in /login > Management > API Configuration. Each attribute must be specified as a different parameter. Each custom field has a maximum length of 1024 characters. The maximum total size of all combined custom fields, including the external key, must be limited to 10KB.

Query examples: start_vpro_session

Start a vPro session with the computer "ABCDEF02" through the Jumpoint "Network01"

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_vpro_session&target=ABCDEF02&jumpoint=Network01

Start a vPro session with the computer "ABCDEF02" through the Jumpoint "Network01" and associate custom attributes with the session

https://support.example.com/api/client_script?type=rep&operation=generate&action=start_vpro_session&target=ABCDEF02&jumpoint=Network01&session.custom.custom_field1=Custom%20Value&session.custom.custom_field2=123

The BeyondTrust representative console script file

ℹ️Note

Command line parameters for the representative console

The BeyondTrust client scripting API

Parameters for client scripting API

Commands

login

⚠️Important

Optional parameters for login

Query examples: login

generate_session_key

Optional parameters for the generate_session_key command

ℹ️Note

Query examples: generate_session_key

push_and_start_local

Required parameter for push_and_start_local

Optional parameter for push_and_start_local

Query examples: push_and_start_local

push_and_start_remote

Required parameter for push_and_start_remote

Optional parameters for push_and_start_remote

start_jump_item_session

Optional parameters for the start_jump_item_session command

⚠️Important

Query examples: start_jump_item_session

ℹ️Note

start_rdp_session

Required parameter for the start_rdp_session command

Optional parameters for the start_rdp_session command

Query examples: start_rdp_session

start_shell_jump_session

Required parameter for the start_shell_jump_session command

Optional parameters for the start_shell_jump_session command

Query examples: start_shell_jump_session

start_vnc_session

Required parameter for the start_vnc_session command

Optional parameters for the start_vnc_session command

Query examples: start_vnc_session

start_vpro_session

Required parameters for the start_vpro_session command

ℹ️Note

Optional parameter for the start_vpro_session command

Query examples: start_vpro_session

ℹ️
Note

⚠️
Important

ℹ️
Note

⚠️
Important

ℹ️
Note

ℹ️
Note