Privilege Management Cloud API

Authenticate to the PM Cloud API

API requests are executed by sending an HTTP request to PM Cloud. 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 Configuration > Settings > API Settings 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.

For more information about creating an API account, please see Configure Access to the Management API in the Privilege Management Cloud Administration Guide.

Create a Token

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

https://example-services.pm.beyondtrustcloud.com/oauth/connect/token

Replace "example" with your production sub-domain name, as shown:

https://[yourProductionSub-domainName]-services.pm.beyondtrustcloud.com/oauth/connect/token

The OAuth client ID and client secret associated with the API account should be included in the POST body:

grant_type=client_credentials&client_id=[yourClientId]&client_secret=[yourGeneratedClientSecret]

If the request is processed without error, you will get an access token JSON response:

{
    "access_token":"<token>",
    "token_type":"Bearer",
    "expires_in":3600,
    "scope":"urn:management:api"
}

The client secret cannot be modified, but it can be regenerated on the Configuration > Settings > API Settings 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:

https://example-services.pm.beyondtrustcloud.com/management-api/v1/Groups

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 "HTTP 401 Unauthorized" response.