Command API
The command API is designed to send commands to your BeyondTrust site from an outside application. Commands can get or set session attributes, join an existing session, or terminate a session. You can also check the health of your B Series Appliance or get information about your BeyondTrust API version.
Commands are executed by sending an HTTP request to the B Series Appliance. Send the request using any HTTPS-capable socket library, scripting language module, or URL fetcher such as cURL or wget. Use either GET or POST as the request method.
POST requests must include a "Content-Type: application/x-www-form-urlencoded" HTTP header when supplying parameters in the request body, and the parameters must be url-encoded. Multipart POST requests are not supported.
Important
When making consecutive API calls, you must close the connection after each API call.
The command API URL is https://access.example.com/api/command.
An XML schema describing the command API response format is available at https://access.example.com/api/command.xsd.
Note
The command API is an authenticated API. The API account must have read-only or full access to the command API.
For instructions on using authenticated APIs using OAuth, see Authenticate to the API.
Required parameter for command API
| action=[string] |
The type of action to perform. Can be any of the following: |
Important
If you experience a high volume of support requests, repeatedly calling a command such as get_logged_in_reps might bottleneck your system. Therefore, a best practice is to not request a list of representatives with each support request. Instead, if making the same API call in succession, consider caching the results for a period of time and reusing them. New sessions requests should reference the cached list instead of calling for the list each time.
The command API returns XML responses that declare a namespace. If you are parsing these responses with a namespace-aware parser, you need to set the namespace appropriately or ignore the namespace while parsing the XML.
- Command API: https://www.beyondtrust.com/namespaces/API/command
Note
The above namespace is returned XML data and is not a functional URL.
check_health
The check_health command returns XML data containing information about the B Series Appliance.
XML response for check_health query
| <appliance> | The hostname of the B Series Appliance. Also contains an id attribute that contains the B Series Appliance's GUID. |
| <version> | The version number and build number of the BeyondTrust software running on the B Series Appliance. |
| <success> | Integer value (1 or 0) indicating if the health check of the B Series Appliance was successful. |
| <error_message> | Returns an error message if a problem is found. If no error is found, this element will not be returned. |
| <failover_role> | The role the B Series Appliance plays in the failover relationship. Can be one of none (if failover is not configured), primary, or backup. |
| <enabled_shared_ips> | Contains an <ip> element for each IP address which is shared between the primary and backup B Series Appliances. If no shared IP addresses are enabled or if failover is not configured, this element is not returned. |
| <last_data_sync_time> | The date and time at which the last data sync occurred between the primary and backup B Series Appliances. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the data sync time as a UNIX timestamp (UTC). If failover is not configured, this element is not returned. |
| <last_data_sync_status> | Contains a string showing the status of the last data sync. If failover is not configured, this element is not returned. |
Query example: check_health
https://access.example.com/api/command?action=check_health
HTTP status check
As an addition or alternative to using the API command above, you can use https://access.example.com/check_health to check the health of a B Series Appliance. This returns an HTTP status of 200 if the probe is successful and 500 (Server Error) if not. While you will see a simple human-readable message showing success or failure, no other data is exposed.
get_connected_clients
The get_connected_clients command returns XML data containing details of all connected BeyondTrust clients.
Required parameters for get_connected_clients
| type=[string] | The types of clients to return in the results. Can be a comma-separated list of values. Supported values are all (default), representative, support_customer, and push_agent. |
| id=[string] | The ID of the client. To get client IDs, see get_connected_client_list . Can be a comma-separated list of values. A maximum of 100 IDs is supported. This ID is a unique identifier which remains valid only while the client is connected. |
| include_connections=[boolean] | If this is set to 1, then the client's list of connections to B Series Appliances and an event log about those connections will be included in the results. |
XML response for get_connected_clients
| <connected_clients> | Contains a child element for each connected client, including <connected_representative>, <connected_support_customer>, <connected_presentation_attendee>, and <connected_push_agent>. |
Element names and attributes
/connected_clients/connected_representative
| id (attribute) | A unique identifier which remains valid only while the client is connected. |
| <client_connections> | Contains a <client_connections> element and an <event_log> element. This element is returned only if the query specifies include_connections. |
| <hostname> | The hostname of the representative’s computer. |
| <platform> | The operating system of the representative’s computer. Also contains an id attribute that briefly notes the selected platform for the client. |
| <timezone_offset> | The number of seconds away from UTC. |
| <connected_since> | The date and time at which this connection was made. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). This element is returned only if the query specifies include_connections. |
| <user_id> | Unique ID assigned to the representative. |
| <type> | The type of account the representative is using. Can be one of Normal or Invited. |
| <username> | The username assigned to the representative. |
| <public_display_name> | The public display name assigned to the representative. Note that this field contains the public display name's value at the time of the conference, which may not match the current value if the public_display_name has subsequently been changed. |
| <private_display_name> | The private display name assigned to the representative. Note that this field contains the private display name's value at the time of the conference, which may not match the current value if the private_display_name has subsequently been changed. |
| <start_session_url> | A URL that can be sent to a customer to start a support session with the representative. |
| <presentation_count> | The number of presentations the representative is performing. Can be either 0 or 1. |
| <support_session_count> | The number of sessions the representative is participating in. |
| <showing_on_rep_list> | Integer value (1 or 0) indicating if the representative appears in the representative list on the public site. |
| <routing_idle> | Integer value (1 or 0) indicating if the representative has a status of idle. |
| <routing_busy> | Integer value (1 or 0) indicating if the representative has a status of busy. |
| <routing_enabled> | Integer value (1 or 0) indicating if the representative has automatic session assignment enabled or disabled. |
| <routing_available> | Integer value (1 or 0) indicating if the representative is available to have sessions automatically assigned. |
| <support_license> | The type of license used by the representative. |
| <support_session_lsids> | Contains an element for each session in which the representative is participating. This field corresponds with the field of the <connected_support_customer> element. |
/connected_clients/connected_support_customer
| id (attribute) | A unique identifier which remains valid only while the client is connected. |
| <client_connections> | Contains a <client_connections> element and an <event_log> element. This element is returned only if the query specifies include_connections. |
| <hostname> | The hostname of the customer’s computer. |
| <platform> | The operating system of the customer’s computer. Also contains an id attribute that briefly notes the selected platform for the client. |
| <timezone_offset> | The number of seconds away from UTC. |
| <connected_since> | The date and time at which this connection was made. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). This element is returned only if the query specifies include_connections. |
| <name> | The name which the customer entered in the Your Name field of the front-end survey or which was assigned programmatically. |
| <non_interactive> | Indicates if the session is a remote desktop protocol (RDP) session or a Shell Jump session. Can be either rdp or shelljump. If neither, this element is not returned. |
| <lsid> | A string which uniquely identifies this session. This field corresponds with the field of the <connected_representative> element. |
/connected_clients/connected_presentation_attendee
| id (attribute) | A unique identifier which remains valid only while the client is connected. |
| <client_connections> | Contains a <client_connections> element and an <event_log> element. This element is returned only if the query specifies include_connections. |
| <hostname> | The hostname of the attendee’s computer. |
| <platform> | The operating system of the attendee’s computer. Also contains an id attribute that briefly notes the selected platform for the client. |
| <timezone_offset> | The number of seconds away from UTC. |
| <connected_since> | The date and time at which this connection was made. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). This element is returned only if the query specifies include_connections. |
| <name> | The name which the attendee entered when joining the presentation or which was assigned programmatically. |
/connected_clients/connected_push_agent
| id (attribute) | A unique identifier which remains valid only while the client is connected. |
| <client_connections> | Contains a <client_connection> element and an <event_log> element. This element is returned only if the query specifies include_connections. |
| <hostname> | The hostname of the Jumpoint’s host computer. |
| <platform> | The operating system of the Jumpoint’s host computer. Also contains an id attribute that briefly notes the selected platform for the client. |
| <timezone_offset> | The number of seconds away from UTC. |
| <connected_since> | The date and time at which this connection was made. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). This element is returned only if the query specifies include_connections. |
| <name> | The Jumpoint's name. |
/client_connection
| <appliance_id> | The GUID of the B Series Appliance to which the client is connected. |
| <purpose> | The reason the representative is connected to this B Series Appliance. Can be either primary or traffic. If not part of a cluster, this will always be primary. |
| <receive_traffic_node> | Integer value (1 or 0) indicating whether this is the client's default traffic node or not. If not part of a cluster, this will always be 0. |
| <connected_since> | The date and time at which the client connected. Data is returned in ISO 8601 format. Also contains a ts attribute which displays the connection start time as a UNIX timestamp (UTC). |
| <private_ip> | The client's private IP address that was used to connect to the B Series Appliance. |
/event_log
| <event> | An <event> element is created for each event that took place during this connection. Up to the last 20 events are returned. Events detail when and why a client connected to a B Series Appliance. Events also include failures to connect to nodes and normal disconnects. Includes a ts attribute which displays the timestamp of the event. |
Query examples: get_connected_clients
- Get a detailed list of all connected clients
https://access.example.com/api/command?action=get_connected_clients
- Get a detailed list of all connected representatives
https://access.example.com/api/command?action=get_connected_clients&type=representative
- Get a detailed list of all connected representatives and support customers
https://access.example.com/api/command?action=get_connected_clients&type=representative,support_customer
- Get a detailed list of all clients with IDs 101, 102, and 103
https://access.example.com/api/command?action=get_connected_clients&id=101,102,103
- Get a detailed list of all clients with IDs 101, 102, and 103 AND whose type is representative or customer
https://access.example.com/api/command?action=get_connected_clients&id=101,102,103&type=representative,support_customer
- Get a detailed list, with connection information, of all connected clients
https://access.example.com/api/command?action=get_connected_clients&include_connections=1
- Get a detailed list, with connection information, of all connected representatives
https://access.example.com/api/command?action=get_connected_clients&type=representative&include_connections=1
- Get a detailed list, with connection information, of all connected representatives and support customers
https://access.example.com/api/command?action=get_connected_clients&type=representative,support_customer&include_connections=1
- Get a detailed list, with connection information, of all clients with IDs 101, 102, and 103
https://access.example.com/api/command?action=get_connected_clients&id=101,102,103&include_connections=1
- Get a detailed list, with connection information, of all clients with IDs 101, 102, and 103 AND whose type is representative or customer
https://access.example.com/api/command?action=get_connected_clients&id=101,102,103&type=representative,support_customer&include_connections=1
get_connected_client_list
The get_connected_client_list command returns XML data containing a summary or list of all connected BeyondTrust clients.
Optional parameters for get_connected_client_list
| type=[string] | The types of clients to return in the results. Can be a comma-separated list of values. Supported values are all (default), representative, support_customer, presentation_attendee, and push_agent. Currently, pinned_client is not a possible value. If the count of pinned Jump Clients is needed in the summary, then all must be specified. |
| summary_only=[boolean] | To return only a summary, set this to 1. |
XML response for get_connected_client_list
| <connected_client_list> | Contains a <connected_client_summary> element with a summary of the data. Also contains a <connected_client> element for each client currently connected to the B Series Appliance. If an error occurs, it will contain an <error> element describing the problem. |
Element names and attributes
/connected_client_list/connected_client_summary
| <appliance_summary> | An <appliance_summary> element is created for each connected B Series Appliance. |
/connected_client_list/connected_client_summary/appliance_summary
| id (attribute) | The B Series Appliance's GUID. |
| <count> | A <count> element is created for each type of client connected to this B Series Appliance. |
/connected_client_list/connected_client_summary/appliance_summary/count
| type (attribute) | The type of client connected to the B Series Appliance. Can be one of representative, support_customer, presentation_attendee, push_agent, or pinned_client. |
/connected_client_list/connected_client
| type (attribute) | The type of client connected to one of the clustered B Series Appliances. Can be one of representative, support_customer, presentation_attendee, or push_agent. |
| id (attribute) | A unique identifier which remains valid only while the client is connected. |
Query examples: get_connected_client_list
- Get a list of all connected clients
https://access.example.com/api/command?action=get_connected_client_list
- Get a list of all connected representatives
https://access.example.com/api/command?action=get_connected_client_list&type=representative
- Get a list of all connected representatives and support customers
https://access.example.com/api/command?action=get_connected_client_list&type=representative,support_customer
- Get a summary of all connected clients
https://access.example.com/api/command?action=get_connected_client_list&summary_only=1
- Get a summary of all connected representatives
https://access.example.com/api/command?action=get_connected_client_list&summary_only=1&type=representative
- Get a summary of all connected representatives and support customers
https://access.example.com/api/command?action=get_connected_client_list&summary_only=1&type=representative,support_customer
get_logged_in_reps
The get_logged_in_reps request returns XML data about all logged-in representatives. It requires no additional parameters.
XML response for get_logged_in_reps query
| <logged_in_reps> | Returns a <rep> element for each logged-in representative. If no representatives are logged in, this element will contain no <rep> elements. If an error occurs, it will contain an <error> element describing the problem. |
Element names and attributes
| id (attribute) | Unique ID assigned to the representative. |
| <display_name> | This element is deprecated as of API version 1.10.0 but still exists for backwards compatibility. Its value is the same as that of <public_display_name>. |
| <public_display_name> | The public display name currently assigned to the representative. |
| <private_display_name> | The private display name currently assigned to the representative. |
| <type> | The type of rep logged in. Types include Normal and Invited. |
| <direct_link> | An HTML anchor tag containing the URL that customers can use to download the customer client to connect directly to the representative. |
| <logged_in_since> | The date and time at which the representative logged in. |
| <presentation_count> | The number of active presentations the representative is currently running. |
| <support_session_count> | The number of active sessions the representative is currently running. |
| <showing_on_rep_list> | Integer value (1 or 0) indicating if the rep has permission to show on the public site and has the Showing On Representative List option checked in the access console. |
Query example: get_logged_in_reps
<https://access.example.com/api/command?action=get_logged_in_reps>
Important
If you experience a high volume of support requests, repeatedly calling a command such as get_logged_in_reps might bottleneck your system. Therefore, a best practice is to not request a list of representatives or teams with each support request. Instead, if making the same API call in succession, consider caching the results for a period of time and reusing them. New sessions requests should reference the cached list instead of calling for the list each time.
get_session_attributes
The get_session_attributes command returns attributes set for an active session.
In order to issue the get_session_attributes command, you must supply the username and password for a BeyondTrust user account. That account must have the permission Allowed to Use Command API along with the permission Administrator.
Required parameter for get_session_attributes
| lsid=[string] | The ID of the session whose attributes you wish to get. The session must currently be active. |
XML response for get_session_attributes query
| <custom_attributes> | Contains a <custom_attribute> element for each custom attribute set for the session. |
| <error> | Returns an error message if the attributes were not retrieved successfully. |
Element names and attributes
/custom_attributes/custom_attribute
| display_name (attribute) | The display name assigned to the custom attribute. |
| code_name (attribute) | The code name assigned to the custom attribute. |
Query example: get_session_attributes
- Get custom attributes for session c69a8e10bea9428f816cfababe9815fe
https://access.example.com/api/command?action=get_session_attributes&lsid=c69a8e10bea9428f816cfababe9815fe
import_jump_shortcut
The import_jump_shortcut command creates a Jump shortcut. When dealing with a large number of Jump shortcuts, it may be easier to import them programmatically than to add them one by one in the access console.
Required parameters for import_jump_shortcut - Local Jump
| name=[string] | The name of the endpoint to be accessed by this Jump Item. This name identifies the item in the session tabs. This string has a maximum of 128 characters. |
| local_jump_hostname=[string] | The hostname of the endpoint to be accessed by this Jump Item. This string has a maximum of 128 characters. |
| group=[string] | The code name of the Jump Group with which this Jump Item should be associated. When using the import method, a Jump Item cannot be associated with a personal list of Jump Items. |
Optional parameters for import_jump_shortcut - Local Jump
| tag=[string] | You can organize your Jump Items into categories by adding a tag. This string has a maximum of 1024 characters. |
| comments=[string] | You can add comments to your Jump Items. This string has a maximum of 1024 characters. |
| jump_policy=[string] | The code name of a Jump Policy. You can specify a Jump Policy to manage access to this Jump Item. |
| session_policy=[string] | The code name of a session policy. You can specify a session policy to manage the permissions available on this Jump Item. |
Required parameters for import_jump_shortcut - Remote Jump
| name=[string] | The name of the endpoint to be accessed by this Jump Item. This name identifies the item in the session tabs. This string has a maximum of 128 characters. |
| remote_jump_hostname=[string] | The hostname of the endpoint to be accessed by this Jump Item. This string has a maximum of 128 characters. |
| jumpoint=[string] | The code name of the Jumpoint through which the endpoint is accessed. |
| group=[string] | The code name of the Jump Group with which this Jump Item should be associated. When using the import method, a Jump Item cannot be associated with a personal list of Jump Items. |
Optional parameters for import_jump_shortcut - Remote Jump
| tag=[string] | You can organize your Jump Items into categories by adding a tag. This string has a maximum of 1024 characters. |
| comments=[string] | You can add comments to your Jump Items. This string has a maximum of 1024 characters. |
| jump_policy=[string] | The code name of a Jump Policy. You can specify a Jump Policy to manage access to this Jump Item. |
| session_policy=[string] | The code name of a session policy. You can specify a session policy to manage the permissions available on this Jump Item. |
Required parameters for import_jump_shortcut - VNC
| remote_vnc_hostname=[string] | The hostname of the endpoint to be accessed by this Jump Item. This string has a maximum of 128 characters. |
| jumpoint=[string] | The code name of the Jumpoint through which the endpoint is accessed. |
| name=[string] | The name of the endpoint to be accessed by this Jump Item. This name identifies the item in the session tabs. This string has a maximum of 128 characters. |
| group=[string] | The code name of the Jump Group with which this Jump Item should be associated. When using the import method, a Jump Item cannot be associated with a personal list of Jump Items. |
Optional parameters for import_jump_shortcut - VNC
| port=[integer] | A valid port number from 100 to 65535. Defaults to 5900. |
| tag=[string] | You can organize your Jump Items into categories by adding a tag. This string has a maximum of 1024 characters. |
| comments=[string] | You can add comments to your Jump Items. This string has a maximum of 1024 characters. |
| jump_policy=[string] | The code name of a Jump Policy. You can specify a Jump Policy to manage access to this Jump Item. |
Required parameters for import_jump_shortcut - Remote Desktop Protocol
| name=[string] | The name of the endpoint to be accessed by this Jump Item. This name identifies the item in the session tabs. This string has a maximum of 128 characters. |
| remote_rdp_hostname=[string] | The hostname of the endpoint to be accessed by this Jump Item. This string has a maximum of 128 characters. |
| jumpoint=[string] | The code name of the Jumpoint through which the endpoint is accessed. |
| group=[string] | The code name of the Jump Group with which this Jump Item should be associated. When using the import method, a Jump Item cannot be associated with a personal list of Jump Items. |
Optional parameters for import_jump_shortcut - Remote Desktop Protocol
| rdp_username=[string] | The username to sign in as. |
| domain=[string] | The domain the endpoint is on. |
| display_size=[string] | The resolution at which to view the remote system. Can be primary (default - the size of your primary monitor), all (the size of all of your monitors combined), or XxY (where X and Y are a supported width and height combination - e.g., 640x480). |
| quality=[string] | The quality at which to view the remote system. Can be low (2-bit gray scale for the lowest bandwidth consumption), best_perf (default - 8-bit color for fast performance), perf_and_qual (16-bit for medium quality image and performance), best_qual (32-bit for the highest image resolution), or video_opt (VP9 codec for more fluid video). This cannot be changed during the remote desktop protocol (RDP) session. |
| console=[boolean] | 1: Starts a console session. 0: Starts a new session (default). |
| ignore_untrusted=[boolean] | 1: Ignores certificate warnings. 0: Shows a warning if the server's certificate cannot be verified. |
| tag=[string] | You can organize your Jump Items into categories by adding a tag. This string has a maximum of 1024 characters. |
| comments=[string] | You can add comments to your Jump Items. This string has a maximum of 1024 characters. |
| jump_policy=[string] | The code name of a Jump Policy. You can specify a Jump Policy to manage access to this Jump Item. |
| sql_server_hostname=[string] | The hostname of the SQL Server used to access SQL Server Management Studio. This string has a maximum of 64 characters. |
| sql_server_port=[integer] | The port used to access the SQL Server instance. The port value accepts only integers in the range of 1-65535, with 1433 as the default value. |
| sql_server_database=[string] | The database name of the SQL Server instance being accessed.. This string has a maximum of 520 characters. |
| custom_app_name=[string] | The name of the remote application being accessed. This string has a maximum of 520 characters. |
| custom_app_params=[string] | A space-separated list of parameters to pass to the remote application. Parameters with spaces can be delimited using double-quotes. This string has a maximum of 16,000 characters. |
Required parameters for import_jump_shortcut - Shell Jump Shortcut
| name=[string] | The name of the endpoint to be accessed by this Jump Item. This name identifies the item in the session tabs. This string has a maximum of 128 characters. |
| shelljump_hostname=[string] | The hostname of the endpoint to be accessed by this Jump Item. This string has a maximum of 128 characters. |
| jumpoint=[string] | The code name of the Jumpoint through which the endpoint is accessed. |
| protocol=[string] | Can be either ssh or telnet. |
| group=[string] | The code name of the Jump Group with which this Jump Item should be associated. When using the import method, a Jump Item cannot be associated with a personal list of Jump Items. |
Optional parameters for import_jump_shortcut - Shell Jump Shortcut
| shelljump_username=[string] | The username to sign in as. |
| port=[integer] | A valid port number from 1 to 65535. Defaults to 22 if the protocol is ssh or 23 if the protocol is telnet. |
| terminal=[string] | Can be either xterm (default) or VT100. |
| keep_alive=[integer] | The number of seconds between each packet sent to keep an idle session from ending. Can be any number from 0 to 300. 0 disables keep-alive (default). |
| tag=[string] | You can organize your Jump Items into categories by adding a tag. This string has a maximum of 1024 characters. |
| comments=[string] | You can add comments to your Jump Items. This string has a maximum of 1024 characters. |
| jump_policy=[string] | The code name of a Jump Policy. You can specify a Jump Policy to manage access to this Jump Item. |
| session_policy=[string] | The code name of a session policy. You can specify a session policy to manage the permissions available on this Jump Item. |
Required parameters for import_jump_shortcut - Protocol Tunnel Jump Shortcut
| protocol_tunnel_hostname | The hostname of the endpoint to be accessed by this Jump Item. This string has a maximum of 128 characters. |
| jumpoint | The code name of the Jumpoint through which the endpoint is accessed. |
| tcp_tunnels | The list of one or more tunnel definitions. A tunnel definition is a mapping of a TCP port on the local user's system to a TCP port on the remote endpoint. Any connection made to the local port causes a connection to be made to the remote port, allowing data to be tunnelled between local and remote systems. Multiple mappings should be separated by a semicolon. auto->22;3306->3306 In the example above, a randomly assigned local port maps to remote port 22, and local port 3306 maps to remote port 3306. |
| name=[string] | The name of the endpoint to be accessed by this Jump Item. This name identifies the item in the session tabs. This string has a maximum of 128 characters. |
| group | The code name of the Jump Group with which this Jump Item should be associated. When using the import method, a Jump Item cannot be associated with a personal list of Jump Items. |
Optional parameters for import_jump_shortcut - Protocol Tunnel Jump Shortcut
| local_address | The address from which the connection should be made. This can be any address within the 127.x.x.x subrange. The default address is 127.0.0.1. |
| tag | You can organize your Jump Items into categories by adding a tag. This string has a maximum of 1024 characters. |
| comments | You can add comments to your Jump Items. This string has a maximum of 1024 characters. |
| jump_policy | The code name of a Jump Policy. You can specify a Jump Policy to manage access to this Jump Item. |
Required parameters for import_jump_shortcut - Web Jump Shortcut
| website_name | The name of the endpoint to be accessed by this Jump Item. This name identifies the item in the session tabs. This string has a maximum of 128 characters. |
| jumpoint | The code name of the Jumpoint through which the endpoint is accessed. |
| url | The URL of the web site. The URL must begin with either http or https. |
| group | The code name of the Jump Group with which this Jump Item should be associated. When using the import method, a Jump Item cannot be associated with a personal list of Jump Items. |
Optional parameters for import_jump_shortcut - Web Jump Shortcut
| verify_certificate | 1: The site certificate is validated before the session starts; if issues are found, the session will not start. 0: The site certificate is not validated. |
| tag | You can organize your Jump Items into categories by adding a tag. This string has a maximum of 1024 characters. |
| comments | You can add comments to your Jump Items. This string has a maximum of 1024 characters. |
| jump_policy | The code name of a Jump Policy. You can specify a Jump Policy to manage access to this Jump Item. |
| session_policy | The code name of a session policy. You can specify a session policy to manage the permissions available on this Jump Item. |
XML response for import_jump_shortcut Query
| <success> | Returns a message of Successfully imported Jump Item shortcut if the import succeeded. |
| <error> | Returns an error message if the import failed. |
Query examples: import_jump_shortcut
- Import Local Jump shortcut "Endpoint" to the endpoint with hostname "ABCDEF02", pinning it to Jump Group "remote_access"
https://access.example.com/api/command?action=import_jump_shortcut&name=Endpoint&local_jump_hostname=ABCDEF02&group=remote_access
- Import Local Jump shortcut "Endpoint" to the endpoint with hostname "ABCDEF02", pinning it to Jump Group "remote_access" and specifying its tag, comments, Jump Policy, and session policy
https://access.example.com/api/command?action=brimport_jump_shortcut&name=Endpoint&local_jump_hostname=brABCDEF02&group=remote_access&tag=Frequent%20Access&brcomments=Web%20server&jump_policy=Notify&brsession_policy=Servers
- Import Remote Jump shortcut "Endpoint" to the endpoint with hostname "ABCDEF02", accessed through Jumpoint "London", pinning it to Jump Group "remote_access"
https://access.example.com/api/command?action=brimport_jump_shortcut&name=Endpoint&remote_jump_hostname=brABCDEF02&jumpoint=London&group=remote_access
- Import VNC shortcut "Endpoint" to the endpoint with hostname "ABCDEF02", accessed through Jumpoint "London", pinning it to Jump Group "remote_access"
https://access.example.com/api/command?action=brimport_jump_shortcut&name=Endpoint&remote_vnc_hostname=brABCDEF02&jumpoint=London&group=remote_access
- Import VNC shortcut "Endpoint" to the endpoint with hostname "ABCDEF02", accessed through Jumpoint "London", pinning it to Jump Group "remote_access" and specifying its port
https://access.example.com/api/command?action=brimport_jump_shortcut&name=Endpoint&remote_vnc_hostname=brABCDEF02&jumpoint=London&group=remote_access&port=100
- Import RDP shortcut "Endpoint" to the endpoint with hostname "ABCDEF02", accessed through Jumpoint "London", pinning it to Jump Group "remote_access"
https://access.example.com/api/command?action=brimport_jump_shortcut&name=Endpoint&remote_rdp_hostname=brABCDEF02&jumpoint=London&group=remote_access
- Import RDP shortcut "Endpoint" to the endpoint with hostname "ABCDEF02", accessed through Jumpoint "London", pinning it to Jump Group "remote_access" and specifying its username, domain, display size, quality, console session, untrusted certificate action, sql server name, sql server port, sql server database name, remote app name, and remote app parameters
https://access.example.com/api/command?action=brimport_jump_shortcut&name=Endpoint&remote_rdp_hostname=brABCDEF02&jumpoint=London&group=remote_access&rdp_username=bradmin&domain=example&display_size=1280x720&quality=brperf_and_qual&console=1&ignore_untrusted=1&brsql_server_hostname=example.local&sql_server_port=1500&brsql_server_database=example&custom_app_name=sql_server&brcustom_app_params=x,y,z
- Import Shell Jump shortcut "Endpoint" to the endpoint with hostname "ABCDEF02", accessed through Jumpoint "London" over SSH, pinning it to Jump Group "remote_access"
https://access.example.com/api/command?action=brimport_jump_shortcut&name=Endpoint&shelljump_hostname=brABCDEF02&jumpoint=London&protocol=ssh&group=remote_access
- Import Shell Jump shortcut "Endpoint" to the endpoint with hostname "ABCDEF02", accessed through Jumpoint "London" over SSH, pinning it to Jump Group "remote_access", and specifying its username, port, terminal type, and keep-alive settings
https://access.example.com/api/command?action=brimport_jump_shortcut&name=Endpoint&shelljump_hostname=brABCDEF02&jumpoint=London&protocol=ssh&group=remote_access&shelljump_username=admin&port=25&terminal=vt100&brkeep_alive=120
- Import Protocol Tunnel Jump shortcut "Endpoint" to the endpoint with hostname "ABCDEF02", accessed through Jumpoint "London", pinning it to Jump Group "remote_access", with a randomly assigned local port mapping to remote port 22
https://access.example.com/api/command?action=brimport_jump_shortcut&name=Endpoint&brprotocol_tunnel_hostname=ABCDEF02&jumpoint=London&brgroup=remote_access&tcp_tunnels=auto-22
"10-0": "Import Protocol Tunnel Jump shortcut "Endpoint" to the endpoint with hostname "ABCDEF02", accessed through Jumpoint "London", pinning it to Jump Group "remote_access", with a randomly assigned local port mapping to remote port 22, local port 3306 mapping to port 3306, and a local address of 127.0.0.5
"10-1": "
https://access.example.com/api/command?action=brimport_jump_shortcut&name=Endpoint&brprotocol_tunnel_hostname=ABCDEF02&jumpoint=London&brgroup=remote_access&tcp_tunnels=auto-22;3306-3306&brlocal_address=127.0.0.5
"11-0": "Import Web Jump shortcut "Endpoint" to the endpoint with URL "example.com", accessed through Jumpoint "London", pinning it to Jump Group "remote_access"
"11-1": "
https://access.example.com/api/command?action=brimport_jump_shortcut&website_name=Endpoint&url=brexample.com&jumpoint=London&group=remote_access
"12-0": "Import Web Jump shortcut "Endpoint" to the endpoint with URL "example.com", accessed through Jumpoint "London", pinning it to Jump Group "remote_access" and not requiring certificate validation
"12-1": "
https://access.example.com/api/command?action=brimport_jump_shortcut&website_name=Endpoint&url=brexample.com&jumpoint=London&group=remote_access&brverify_certificate=0
logout_rep
The logout_rep command logs out a specified user.
Required parameter for logout_rep
| rep_id=[string] | The unique ID representing the user you wish to logout. |
XML response for logout_rep query
| <success> | Returns a message of Successfully logged out if the logout was successful. |
| <error> | Returns an error message if the logout was not successful. |
Query examples: logout_rep
- User 375 logged out
https://access.example.com/api/command?action=logout_rep&rep_id=375
set_failover_role
The set_failover_role command sets the failover role of a B Series Appliance to either primary or backup.
Required parameter for set_failover_role
| role=[string] | The role to assign to this B Series Appliance. Can be either primary or backup. |
Optional parameters for set_failover_role
| data_sync_first=[boolean] | To perform a data sync with the peer B Series Appliance before failing over, set this to 1. All users on the existing primary B Series Appliance will be disconnected during the data sync, and no other operations will be available until the swap is complete. To fail over without a final data sync, set this to 0. |
| force=[boolean] | This option is only applicable when contacting the primary B Series Appliance and attempting to set its role to backup. If this is set to 1, then this B Series Appliance will become the backup even if the peer B Series Appliance cannot be contacted. |
XML response for set_failover_role query
| <success> | If a data sync is being performed first, returns a message of Successfully started data sync. Role change will occur upon successful completion. Otherwise, returns a message of Successfully changed role. |
| <error> | Returns an error message if the role was not set successfully. |
Query examples: set_failover_role
- Set failover role to primary
https://access.example.com/api/command?action=set_failover_role&role=primary
- Set failover role to backup
https://access.example.com/api/command?action=set_failover_role&role=backup
- Set failover role to primary and perform a data sync
https://access.example.com/api/command?action=set_failover_role&role=primary&data_sync_first=1
- Set failover role to backup and perform a data sync
https://access.example.com/api/command?action=set_failover_role&role=backup&data_sync_first=1
- Set failover role to backup even if the primary B Series Appliance cannot be contacted
https://access.example.com/api/command?action=set_failover_role&role=backup&force=1
- Set failover role to backup even if the primary B Series Appliance cannot be contacted, and perform a data sync
https://access.example.com/api/command?action=set_failover_role&role=backup&data_sync_first=1&force=1
set_session_attributes
The set_session_attributes command sets the external key and other custom attributes for an active session.
Required parameter for set_session_attributes
| lsid=[string] | The ID of the session whose attributes you wish to set. The session must currently be active. |
Optional parameters for set_session_attributes
| session.custom.external_key=[string] | An arbitrary string that can link this session to an identifier on an external system, such as a customer relationship management ticket ID. This has a maximum length of 1024 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
If an attribute is not listed in the URL, it will keep its existing value. To clear an attribute, you must set the attribute to an empty string.
XML response for set_session_attributes query
| <success> | Returns a message of Session attributes were set if the attributes were set successfully. |
| <error> | Returns an error message if the attributes were not set successfully. |
Query examples: set_session_attributes
- Set external key for session c69a8e10bea9428f816cfababe9815fe
https://access.example.com/api/command?action=set_session_attributes&lsid=c69a8e10bea9428f816cfababe9815fe&session.custom.external_key=ABC123
- Set a custom value for session c69a8e10bea9428f816cfababe9815fe
https://access.example.com/api/command?action=brset_session_attributes&lsid=brc69a8e10bea9428f816cfababe9815fe&brsession.custom.custom_field1=Custom%20Value
terminate_session
The terminate_session command terminates a session that is in progress.
Required parameter for terminate_session
| lsid=[string] | The unique ID representing the session you wish to terminate. |
XML response for terminate_session query
| <success> | Returns a message of Successfully terminated if the termination was successful. |
| <error> | Returns an error message if the termination was not successful. |
Query examples: terminate_session
- Session da4b510978a541d49398e88c66e28475 terminated
https://access.example.com/api/command?action=terminate_session&lsid=da4b510978a541d49398e88c66e28475
Updated about 1 month ago