Command API - JSON

Overview

The Command APIs are designed to send commands to your BeyondTrust Privileged Remote Access site from an outside application. Commands can start or transfer a session, get a list of logged-in Users, or obtain a list of teams and issues. You can also check the health of your appliance, change an appliance's failover role, or get information about the permissions of the current API Account.

Authentication

The BeyondTrust Privileged Remote Access Command APIs require OAuth 2 credentials for authentication. To authenticate to the API, you must create an API account on the /login > Management > API Configuration page. The account must have permission to access the Command APIs. Copy the OAuth Client ID and OAuth Client Secret values before saving the API Account. API requests require a token to be generated using this client id and secret and then submitted with each API request.

ℹ️

The OAuth Client Secret cannot be viewed again after the API Account has been saved, but it can be regenerated when you edit the API Account. Regenerating a client secret and then saving the account immediately invalidates any OAuth tokens associated with the account. Any API calls using those tokens will be unable to access the API. A new token must be generated using the new client secret.

The command API URL is https://support.example.com/api/command/v2.

Create a token

Create a token by sending an HTTP POST request to the URL of your BeyondTrust Privileged Remote Access site followed by /oauth2/token:

https\:\/\/support.example.com/oauth2/token

The OAuth client ID and client secret associated with the API account should be Base64 encoded and included in an HTTP basic authorization header:

Authorization: Basic \<base64-encoded "client_id:secret">

Include the following POST body in the request:

grant_type=client_credentials

If the request is processed without error, you receive an access token JSON response:

{
    "access_token": "<token>",
    "token_type": "Bearer",
    "expires_in": 3600
}

ℹ️

This token expires after one hour. Any calls to the API past that point must have a new token. Each API account can have a maximum of 30 valid tokens. If an API account attempts to generate more than 30 tokens, then the oldest token is invalidated before a new one is generated.

Request an API resource

Now that you have an access token, you can make HTTPS requests to the Command APIs. The token obtained above must be included in an Authorization HTTP header with each request:

Authorization: Bearer <token>

If the token is valid, you gain access to the requested URL.

Authentication errors

Requests made to the web API with expired or invalid tokens result in a JSON error response:

{
    "error": "access_denied",
    "message": "The resource owner or authorization server denied the request."
}

🚧

When making consecutive API calls, you must close the connection after each API call.

Request rate limits

Requests are limited to 20 per second and 15,000 per hour. This limit applies to all API endpoints and is per API account. Responses include headers with the rate limit information: Example:

X-RateLimit-Limit: 15000
X-RateLimit-Remaining: 14996

Required Request Headers

In addition to the Authorization header mentioned above for OAuth 2 authentication,

• for GET and DELETE requests, you must include an Accept header with the value application/json.
• for all other requests where you are sending a JSON request body, you must include a Content-Type header with a value of application/json.

HTTP Request Methods

The documentation below lists the allowed HTTP request methods for each API. Not all methods are allowed for all APIs.

All APIs that document GET requests also accept HEAD requests. Responses to HEAD requests never include a body. This might be useful if you only wish to use the HTTP status code to determine the existence of a resource or resources identified by the URI, and you do not need the response body.

In addition to the human-readable documentation for each API below, the OPTIONS method may be used with any URI to obtain the list of allowed HTTP methods for a given URI.

For example, the request

OPTIONS https\:\/\/support.example.com/api/command/v2/user

responds with an Allow header containing a comma-separated list of the HTTP methods that can be used with that URI:

Allow: GET,HEAD

If you attempt to use an HTTP method with an API that does not support that method, you receive an HTTP 405 "Method Not Allowed" response.

Common HTTP Status Codes

Individual APIs may provide specific documentation for certain status codes, but not all possible status codes are documented on every API. The following is a list of the HTTP status codes commonly returned by these APIs and what they usually mean.

Date-Time Formatting and Time Zones

All date-time values should be in RFC3339 Internet Date-Time Format in UTC unless otherwise noted. When submitting date-time values to these APIs, milliseconds are optional and are ignored. A UTC timezone must be included to avoid ambiguity, represented with either the "Z" suffix or a "+00:00" offset suffix.

Valid Examples

• 2025-10-16T14:46:25.930+00:00
• 2026-10-16T14:46:23+00:00
• 2025-10-16T14:46:25.930Z
• 2026-10-16T14:46:23Z

Invalid Examples

• INVALID 2025-10-16T14:46:25.930: Missing timezone; not a valid RFC3339 string.
• INVALID 2026-10-16T14:46:23: Missing timezone; not a valid RFC3339 string.
• INVALID 2025-10-16T14:46:25.930-08:00: Non-UTC timezone; valid RFC3339 string but not allowed by these APIs.
• INVALID 2026-10-16T14:46:23+04:00: Non-UTC timezone; valid RFC3339 string but not allowed by these APIs.

Date-time strings in responses always include a "+00:00" timezone offset suffix - never a "Z" suffix.

Integers

Request body parameters that are marked as type "integer" must be supplied as actual JSON numbers, not strings containing a number. For example, if the documentation indicates a request body field named team_id is an integer, then the object {team_id: 42} is valid, but the object {team_id: "42"} is invalid.

Changes

From time to time, new fields may be added to existing API responses to support new features, without changing any existing fields. Ensure that your client code is written in such a way it can handle or ignore these minor additions to existing API responses.

Base Path

The base path on all API call URLs must be /api/command/v2. In the documentation below, the base path is omitted for brevity. When constructing the URL for a particular API, combine your hostname, the base path, and then the documented path of the API you wish to call. For example, the full URL for the API to get a user with a specific id is:

"https://" + "support.example.com" (hostname) + "/api/command/v2" (base path) + "/user/{id}" (API path)

If you wanted to get the user with id 5, your final URL would be

<https://support.example.com/api/command/v2/user/5>

Miscellaneous

GET /openapi.yaml

Returns a YAML document containing an OpenAPI specification for all available BeyondTrust Privileged Remote Access Command APIs. Many tools exist that can read this document and generate useful resources, such as:

• Client code for interacting with the API
• Various forms of API documentation

ℹ️

If you're reading this on a web page, the page was likely generated from a response to this API.

Responses

API Info

GET /info

Returns general information about the Command APIs, such as version, as well as the permissions of the API Account whose credentials were used to authenticate the request.

Responses

Schema

permissions object - The current API Account's permissions.

Top-level fields

Health

GET /health

Returns appliance health and status information needed for failover purposes.

ℹ️

If this request is sent more than once per minute, a cached response may be returned.

Responses

Appliances

GET /appliance

Returns information about all configured appliances, including their failover role and cluster role.

Responses

GET /appliance/client-count

Get a list of appliances along with counts for each type of client connected to that appliance.

Query Parameters

Responses

Clients

GET /client

Get details of all connected BeyondTrust Privileged Remote Access clients, optionally filtered by client type.

Query Parameters

Responses

GET /client/{id}

Get details of a connected client identified by {id}.

ℹ️

The id is only valid while the client is connected. Requests for a client that has since disconnected return 404.

Path Parameters

Responses

GET /client/{id}/connections

Get a list of connections and an event log about those connections for the client with the given {id}.

ℹ️

The id is only valid while the client is connected. Requests for a client that has since disconnected return 404.

Path Parameters

Responses

Sessions

GET /session/{lsid}

Returns attributes for an active support session identified by {lsid}.

Path Parameters

Responses

PATCH /session/{lsid}

Set the external key or other custom attributes for an active support session identified by {lsid}. Each field is identified by its code name as configured in /login > Configuration > Custom Fields.

Path Parameters

Request Body - application/json

A key/value object of custom field code names and their values.

ℹ️

Custom Fields

• Fields must be configured in /login > Configuration > Custom Fields before use
• Maximum of 30 fields per request
• Maximum of 1024 characters per value

Responses

DELETE /session/{lsid}

Terminates an active support session identified by {lsid}.

🚧

This action immediately terminates the session for all participants. It cannot be undone.

Path Parameters

Responses

Users

GET /user

Get a list of all logged-in Users, both normal and invited.

Responses

POST /user/{id}/logout

Force a logged-in User identified by {id} to log out.

🚧

This immediately terminates the User's console session. Any sessions they are participating in may be affected.

Path Parameters

Responses

Failover

POST /failover-role

Set the failover role of an appliance to either primary or backup.

🚧

This is a disruptive operation. Setting data_sync_first to true disconnects all users on the existing primary appliance and blocks all other operations until the swap is complete.

Request Body - application/json

Responses

Schemas

ObjectId

A numeric identifier used throughout the API to reference resources such as Users.

ApplianceId

A GUID that uniquely identifies an appliance.

Username

The username of a User.

LSID

A string that uniquely identifies a session.

CodeName

The code name of a resource. Must be unique.

MessageResponse

A general success or failure message returned by many endpoints.

ErrorBagResponse

Key/value pairs returned for input validation errors. Keys are request field names; values are arrays of error messages for that field.

IPv4Address

IPv6Address

Client

Base schema shared by AccessConsole, AssetClient, and Gateway.

AccessConsole

Extends Client. Represents a User logged into the Access Console.

ℹ️

The private_display_name and public_display_name field descriptions appear transposed in the source. Verify the correct mapping in your environment.

AssetClient

Extends Client. Represents a non-interactive client connection.

Gateway

Extends Client. No additional fields beyond the base Client schema.

HealthBase

Returned by GET /health. Contains appliance health and failover status information.

Parameters

IdParam

A reusable path parameter used across endpoints to identify a specific resource by its numeric ID.

Responses

404NotFound

422UnprocessableEntity

Example Response

json
{
  "message": "Validation failed.",
  "errors": {
    "queue_id": ["The queue_id field must be an integer."],
    "priority": ["The priority field must be between 1 and 3."]
  }
}