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>​​'
    

    📘

    Note

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

Did this page help you?