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:

• Go: https://github.com/SSHcom/privx-sdk-go
• Python​: ​https://github.com/SSHcom/privx-sdk-for-python​​

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 an API-client entry in PrivX.

   In the PrivX GUI, go to ​Settings→Deployment→Integrate with PrivX using API clients​​, then click ​Add API Client​​.

2. Provide a ​Name​ for the API client. To provide permissions, also add some ​Roles​​ for 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.

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​​):

   Bash

   $ 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:

   JSON

   {
        "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:

   Bash

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