API configuration

What is API configuration?

API configuration involves setting up the application programming interface (API) to allow secure and efficient communication between the B Series Appliance and external systems, enabling integration with other services.

How is API configuration useful for the B Series Appliance?

API configuration allows administrators to automate tasks, integrate third-party tools, and extend the functionality of the B Series Appliance, improving workflows and streamlining operations.

How do I access the API Configuration page?

1. Use a Chromium-based browser to sign in to your Privileged Remote Access URL.
   This URL is provided in the BeyondTrust welcome email and includes your site URL followed by /login.
2. From the left menu, click Management.
   The Software page opens and displays by default.
3. At the top of the page, click API Configuration.
   The API Configuration page displays.

How to enable the API and set up access

Enable XML API

Choose to enable the BeyondTrust XML API, allowing you to run reports and issue commands such as starting or transferring sessions from external applications, as well as to automatically back up your software configuration.

CLI client download

The Command Line Interface (CLI) tool can be downloaded to make it easier to use and configure APIs and automation scripts, and integrate them with your BeyondTrust Privileged Remote Access installation. The CLI tool is available for Windows (x64), macOS, and Linux (x64) platforms. Select the appropriate platform and click Download BTAPI CLI Client.

The download is a compressed executable file. Extract the file, and save or link it from an executable area (in your PATH).

• For Windows systems: Open the file in a terminal such as Windows Command Prompt or Windows PowerShell.
• For macOS systems: Run the file in the terminal.

The Help information, including options, commands, and variable instructions, display when the program opens.

ℹ️

Note

For more information on creating APIs with CLI, see use case examples in the BeyondTrust Privileged Remote Access API Guide.

API accounts

An API account stores all of the authentication and authorization settings for the API client. At least one API account is required to use the API, either in conjunction with the Integration Client, with a third-party app, or with your own in-house developed software.

Add an API account, edit, delete

Create a new account, modify an existing account, or remove an existing account.

Add or edit an API account

Enabled

If checked, this account is allowed to authenticate to the API. When an account is disabled, all OAuth tokens associated with the account are immediately disabled.

Name

Create a unique name to help identify this account.

Comments

Add comments to help identify the purpose of this object.

OAuth client ID

The OAuth client ID is a unique ID generated by the B Series Appliance. It cannot be modified. The client ID is considered public information and, therefore, can be shared without compromising the security of the integration.

OAuth client secret

The OAuth client secret is generated by the B Series Appliance using a cryptographically secure pseudo-random number generator.

ℹ️

Note

The client secret cannot be modified, but it can be regenerated on the Edit page. Regenerating a client secret and then saving the account immediately invalidates any OAuth tokens associated with the account. Any API calls using those tokens cannot access the API.

ℹ️

Note

The OAuth client ID and client secret are used to create OAuth tokens, necessary for authenticating to the API.

Permissions

Select the areas of the API this account is allowed to use.

For the Command API, choose to deny access, to allow read-only access, or to allow full access.

For the Reporting API, check the allowed permissions:

• Allow Access to Access Session Reports and Recordings
• Allow Access to License Usage Reports
• Allow Access to Vault Account Activity Reports
• Allow Access to Jump Item Reports
• Allow Access to Syslog Reports

For the Backup API, check to Allow Access and to Allow Vault Encryption Key Access.

The Configuration API allows for the management and configuration of common tasks in /login, which can be automated and work with your orchestration processes. Check to Allow Access and, if access is allowed, check if this API can Manage Vault Accounts.

Check to allow access to the Endpoint Credential Manager API.

• If ECM groups are enabled on the site, select which ECM group to use. ECMs that are not associated with a group come under Default.

The SCIM API allows the option to provision users from a different security provider. If you allow access to the SCIM API, the option Allow long-lived bearer token becomes available. Allowing long-lived tokens is not recommended unless it is required by your SCIM client, as these bearer tokens never expire. Because all other API permissions require tokens with a one-hour expiry, enabling long-lived tokens for SCIM disables all other API permissions.

Network restrictions

List network address prefixes from which this account can authenticate.

ℹ️

Note

API accounts are not restricted by the network prefixes configured on the /login > Management > Security page. They are restricted only by the network prefixes configured for the API account.

ECM groups

ℹ️

Note

This feature is only present if enabled when your site is built. If it is not present, please contact your site administrator.

The ECM Groups feature provides support for multiple disconnected credential providers. It allows a single PRA deployment to integrate with multiple external credential providers like Password Safe or Privileged Identity. These can be located at various remote locations through multiple ECM instances.

New ECM group name

Create a unique name to help identify this ECM group. You can configure up to fifty ECM groups.