Skip to main content

Setting Up Client Connections to the API

The Key Manager API can be used with any external client that supports HTTP requests, HTTP methods, and HTTP headers sent over HTTPS. One possible and widely available client is curl.

All clients must authorize to the API using valid API tokens. API tokens are associated to Key Manager administrator accounts. When a valid API token is used for connecting to the API, the client is given the same permissions given to the associated Key Manager administrator account. Key Manager administrators with the permission to Administer the users, groups and permissions can generate API tokens for any Key Manager administrator. Key Manager administrators with the permission to Connect through external API can generate API tokens for their own account.

API tokens can be created and revoked via the Key Manager GUI, on the Accounts→API tokens page.

You can use any currently-valid API token to authorize to the API. For example, with curl.

caution

In curl the API token is provided directly in the command, which may compromise the API token similarly to any other credential that is typed directly in the terminal. The provided curl examples are intended for illustration purposes only. In production environments API tokens should never be provided directly on a terminal.

$ curl -X GET -H "Authorization: Bearer <API token>" \
-H "Accept: application/json; indent=4" \
"https://frontend.example.com/api/v3/"

An API token is a short string, such as wMBrgbzzp9A4N4diX9oBXxDU3CjNLP. A working example of an API request would be:

$ curl -X GET -H "Authorization: Bearer wMBrgbzzp9A4N4diX9oBXxDU3CjNLP" \
-H "Accept: application/json; indent=4" \
"https://frontend.example.com/api/v3/"

When the API token is valid, the previous command returns a JSON object describing the available API endpoints.

You can then use the API by connecting to the appropriate endpoint. For example, to list all the hosts in the managed environment:

$ curl -X GET -H "Authorization: Bearer wMBrgbzzp9A4N4diX9oBXxDU3CjNLP" \
-H "Accept: application/json; indent=4" \
"https://frontend.example.com/api/v3/hosts/"
note

If your Key Manager front end uses self-signed server certificates, you will need to allow insecure connections by adding the --insecure option to your curl commands.

Self-signed server certificates are only recommended for evaluation use. For production environments we strongly recommend installing trusted server certificates on all Key Manager components. For information about setting up trusted server certificates, see the PrivX Key Manager Installation Manuals.

Internal API Tokens​

Internal API tokens are used by backend:hostexecutor and have the following format (note the two underscores):

__<increasing number>@<ukm-backend-server>

If you revoke an internal API token, it will be deleted. If an internal API token is not anymore valid, the next time host-executor starts, it will create a new internal API token.