EPM FOR WINDOWS AND MAC API

EPM ships with the following APIs:

• Management API: Designed to interact with group, computer, policy, and event entities in similar ways as the EPM console user interface allows. The Management API gives you custom control over managing computers, groups, and policies through your own scripts or applications, and reporting on events.

The Management API is an authenticated API.

• SCIM API: Designed for integration between EPM and third-party identity management providers like Okta, and potentially any provider that adheres to the SCIM protocol.

Through the SCIM API, you can provision and manage EPM users in a 3rd party identity management provider which follows the SCIM protocol. This allows for better automation with CRUD operations and better visibility with governance and compliance.

ℹ️

Note

For more information on authentication, see Authenticate to the API.

Use cases

Front-end-integration of the Management API enables you to better integrate your specific processes into your privilege management of endpoints.

Common use cases include:

• Managing computers and groups, which consists of common CRUD operations.
• Moving a computer from one group to another.
• CRUD operations for policy data. An example use case is assigning a policy to a computer group to test a pre-production policy.
• Retrieving endpoint events via a plethora of filters.

Authenticate to the API

API requests are executed by sending an HTTP request to EPM. 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.

ℹ️

Note

For more information about creating an API account, see Configure Access to the Management API in the Endpoint Privilege Management User 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]

Send the POST request using an HTTP client. Ensure the

Content-Type

header is set to

application/x-www-form-urlencoded

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"
}

ℹ️

Note

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 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.

The API documentation includes a complete list of methods, models, and usage descriptions and examples.

• Access the API Reference from the top banner API Reference.
• Try out and test examples using the Swagger UI.

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

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

ℹ️

Note

For more information on Swagger, see Swagger UI.

Request rate limits

Requests are limited to 1000 requests every 100 seconds.