Authenticate to the Privileged Remote Access API

API requests are executed by sending an HTTP request to the B Series Appliance. Send the request using any HTTPS-capable socket library or scripting language module, URL fetcher such as cURL, or an OAuth library specific to your platform. BeyondTrust's web APIs use OAuth as the authentication method.

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 necessary APIs. API requests require a token to first be created and then be submitted with each API request.

For more information, please see the following:

For creating an API account, API Configuration: Enable the XML API and Configure Custom Fields
Example API request at Test Scenario

Create a Token

Create a token by POSTing to the URL of your BeyondTrust site followed by /oauth2/token:

https://access.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 will 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 afterward 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.

The client secret cannot be modified, but it can be regenerated on the /login > Management > API Configuration 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 are unable to access the API. A new token must be generated using the new client secret.

Request an API Resource

Now that you have an access token, you can make GET/POST requests via HTTPS to the web API:

https://access.example.com/api/command

The obtained token is used for HTTP authentication and must be included in an HTTP authorization 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:

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