API-Client Integration

You can automate PrivX administrative tasks via the PrivX API.

You can use any RESTful client with OAuth2 support to access the PrivX API, such as curl. You may also use the PrivX SDK, which is available for the following languages:

For accessing PrivX REST API via command line, see privx-cli.

For API specs, see API reference

High-level setup steps include:

  • Providing role-based permissions for the API client.

  • OAuth2 authentication with the API client.

First define the permissions of the API client:

  1. Create PrivX role(s) for granting permissions to your API client. To do this, go to the PrivX GUI Administration→Roles and click Add Role. Within the role settings, enable any Permissions required by your API client.

  2. Create an API-client entry in PrivX: Go to Administration→Deployment→Integrate with PrivX using API clients, then click Add API Client.

    Provide a Name for the API client. To provide permissions, also add the previously-created role(s) to the API client. Click Save to save your API client.

  3. Back on the API clients page, expand the Credentials of your API client. These are required later for authentication setup. Also find the TLS trust anchor from the bottom of the page.

After creating your API-client entry, authenticate using your API client as follows:

  1. Provide your API-client Credentials to the /auth/api/v1/oauth/token endpoint. For example, using curl (replace <privx.example.com> with your PrivX address, replace <oauth_client_id>, <oauth_client_secret>, <api_client_id>, and <api_client_secret> with the respective values from your API-client Credentials):

    $ curl -X POST \
https://<privx.example.com>/auth/api/v1/oauth/token \
-u <oauth_client_id>:<oauth_client_secret> \
--data-urlencode 'grant_type=password' \
--data-urlencode 'username=<api_client_id>' \
--data-urlencode 'password=<api_client_secret>'

Unlike other PrivX-API endpoints, the /auth/api/v1/oauth/token endpoint only accepts content in application/x-www-form-urlencoded format (not in application/JSON format).

Upon successful authentication you will receive an access token in JSON format, similar to the following:

{
        "access_token": "<access_token>",
        "token_type": "bearer",
        "expires_in": 1800
}

  1. You can now use the access token to perform PrivX actions using other endpoints. For example, to list all hosts in PrivX:

    $ curl -X GET \
-H "Authorization: Bearer <access_token>" \
https://<privx.example.com>/host-store/api/v1/hosts

Was this page helpful?