Authenticate to the Privileged Remote Access API
API requests are executed by sending an HTTP request to the 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 be first created and then submitted with each API request. An example API request can be seen in the Test Scenario.
Create a Token
Create a token by POSTing to the URL of your BeyondTrust site followed by
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">
The request should include the following POST body:
If the request is processed without error, you will get an access token JSON response:
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.
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 will be 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:
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.
Requests made to the web API with expired or invalid tokens result in a JSON error response:
- "message":"The resource owner or authorization server denied the request."
When making consecutive API calls, you must close the connection after each API call.