API Configuration: Enable the XML API and Configure Custom Fields

API Configuration

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.

Allow HTTP Access to XML API

This feature is available only to customers who own an on-premises Secure Remote Access Appliance. BeyondTrust Cloud customers do not have access to this feature.

By default, access to the API is SSL-encrypted. However, you can choose to allow unencrypted HTTP access. It is highly recommended that HTTP access be disallowed as a security best practice.

This option has been deprecated as of 16.1 and does not appear to new users. For users upgrading from a version prior to 16.1, the option is still available if you continue to use the deprecated method of authenticating to the API with a user account. If you switch to the preferred method of authenticating with an API account, all API traffic must occur over HTTPS.

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.

Prior to 16.1, a user account was used to authenticate to the API. This method has been deprecated, though for customers already using this method, it is still supported for backward compatibility.

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 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 appliance using a cryptographically secure pseudo-random number generator.

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 will be unable to access the API.

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

For more information, please see the API Guide.

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. Also set if this account can use the Reporting API, the Backup API, and/or the Endpoint Credential Manager API.

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.

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