Privilege Management Cloud API - Version 1

Use the PM Cloud Management API to configure and customize PM Cloud components to interact with external systems and software.

Use this guide as a resource to get started with the PM Cloud API.

This resource is intended for readers with knowledge of HTTPS request and response processing, web development, and JSON notation.

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.

Access PM Cloud API Documentation

The management API is written according to OpenAPI standards. You can view documentation for the API using your preferred OpenAPI tool, such as Swagger, Postman, or RediDoc.

A preconfigured Swagger UI is available as part of the solution. Replace example with the name of your PM Cloud instance in the following URL to access the docs: (https://<example-services.epm.btrusteng.com/management-api>/swagger).

The API documentation includes a complete list of methods, models, and usage descriptions and examples. You can try out and test examples using the Swagger UI.

Alternatively, download the JSON file from the preconfigured Swagger UI and use a tool of your choice to view the documentation.

For more information on Swagger, please see Swagger UI.