Privileged Remote Access configuration APIs

Overview

The BeyondTrust Privileged Remote Access Configuration APIs provide a way to programmatically configure BeyondTrust Privileged Remote Access.

Authentication

The BeyondTrust Privileged Remote Access Configuration APIs require OAuth 2 credentials for authentication.

Required Request Headers

In addition to the Authorization header used 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 will 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 and/or pagination headers 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://access.example.com/api/config/v1/user

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

Allow: GET,HEAD,POST

If you attempt to use an HTTP method with an API that does not support that method, you will 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.

Status Code	Description
200	For a GET query, this indicates the query was successful, though the response may or may not include an empty resource array depending on whether your query parameters matched any resources. For a PATCH request, this indicates the resource was updated successfully, and the response should contain the updated resource object.
201	The operation successfully created a new resource.
204	Indicates an operation—such as a DELETE—completed successfully. The response body should be empty.
401	For a GET operation, this indicates you supplied unrecognized query string parameters; for a POST or PATCH operation, this indicates you supplied unrecognized fields in the request body. Check the documentation to ensure all parameters are spelled correctly.
403	The API Account whose authentication credentials were used for the request does not have permission to use this API. Edit this account on the API Account page and ensure it has permission to use the Configuration API.
404	A request for a specific resource - usually by id - did not match any known resources.
405	Your request contained an HTTP method that is not supported for the URI of the request. The documentation below indicates which methods are allowed for each API endpoint. Methods that are not specifically documented are not allowed, except for HEAD and OPTIONS as mentioned in the HTTP Request Methods section above.
422	This can happen when attempting to create or update a resource with malformed data. The response body should contain a validation error dictionary indicating which fields are invalid and how they are invalid.
500	An internal server error occurred. Please contact BeyondTrust support.

Pagination

All GET API endpoints that return multiple resources — e.g. GET https://access.example.com/api/config/v1/user — return paginated responses of no more than 100 items by default. This means a single response may or may not include all of the requested resources and you may need to make additional requests to obtain the remaining resources.

Query String Parameters

There are two query string parameters you should always supply when accessing a paginated API:

per_page: This indicates the number of resources you wish to obtain in each response. It defaults to 100 if not supplied, which is also the maximum value.
current_page: This indicates the 1-based index of the set of per_page resources you wish to obtain.

There are several response headers you can use to programmatically navigate through all the pages of a given resource.

`Link` Header

The Link header includes the URLs of at least the first and last page of the paginated API endpoint based on your per_page and current_page query string parameters. The header may also contain URLs for the previous and next pages, depending on your pagination query string parameters and how many resources exist in the system. An example Link header for a request to

https\:\/\/access.example.com/api/config/v1/user?per_page=10&current_page=2

would look something like the following:

Link: <https://access.example.com/api/config/v1/user?per_page=10current_page=1>; rel="first",
<https://access.example.com/api/config/v1/user?per_page=10current_page=1>; rel="previous",
<https://access.example.com/api/config/v1/user?per_page=10current_page=3>; rel="next",
<https://access.example.com/api/config/v1/user?per_page=10current_page=5>; rel="last"

*Newlines are included for readability. They would not be included in an actual Link header.

The sections of a Link header are comma-space-delimited. The URLs are surrounded in <>.

The rel values indicate the name of the page identified by the preceding URL. Possible values are "first", "previous", "next", and "last". "first" and "last" URLs will always be included, even if they are the same. "previous" and "next" URLs will only be included when those pages exist.

`X-BT-Pagination` Headers

Using the URLs in the Link header is the least error-prone way to paginate. Building your URLs programmatically is not recommended. However there are additional headers that provide access to some page numbers and resource counts that you may find useful.

X-BT-Pagination-Current-Page: Contains the 1-based index of the current page. This should match your current_page query string parameter, if provided.
X-BT-Pagination-Last-Page: Contains the 1-based index of the last page.
X-BT-Pagination-Per-Page: Contains the 1-based index of the current page. This should match your per_page query string parameter, if provided.
X-BT-Pagination-Total: Contains the total number of resources that match your query across all pages.

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 will be 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 will 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 } would be valid, but the object { team_id: "42" } would be invalid.

Documentation

Find out more about BeyondTrust Privileged Remote Access APIs.