Forming activity service API requests

Token-based authentication is required to access the activity service API. You can authenticate requests with user authentication tokens or allowed certificates.

RBAC API requests must include a URI path following the pattern:

https://<DNS>:4433/activity-api/<VERSION>/<ENDPOINT>

The variable path components derive from:

DNS: Your PE console host's DNS name. You can use localhost, manually enter the DNS name, or use a puppet command (as explained in Using example commands).
VERSION: Either v1 or v2, depending on the endpoint.
ENDPOINT: Either events or events.csv, depending on the endpoint.

For example, you could use any of these paths to call the GET /v1/events endpoint:

https://$(puppet config print server):4433/activity-api/v1/events
https://localhost:4433/activity-api/v1/events
https://puppet.example.dns:4433/activity-api/v1/events

To form a complete curl command, you need to provide appropriate curl arguments, authentication, and you might need to supply additional parameters specific to the endpoint you are calling.

For general information about forming curl commands, authentication in commands, and Windows modifications, go to Using example commands.

Token authentication

You can use token or certificate authentication with the activity service API.

For instructions on generating, configuring, revoking, and deleting authentication tokens in PE, go to Token-based authentication.

To use a token in an request, you can use puppet-access show, such as:

auth_header="X-Authentication: $(puppet-access show)"
uri="https://$(puppet config print server):4433/activity-api/v1/events"

curl --header "$auth_header" "$uri"

Or you can use the actual token, such as:

auth_header="X-Authentication: <TOKEN>"
uri="https://$(puppet config print server):4433/activity-api/v1/events"

curl --header "$auth_header" "$uri"

For general information about forming curl commands, authentication in commands, and Windows modifications, go to Using example commands.

Allowed certificate authentication

You can authenticate requests with a certificate listed in RBAC's certificate allowlist, which is located at:

/etc/puppetlabs/console-services/rbac-certificate-allowlist

Important: If you edit the rbac-certificate-allowlist file, you must reload the pe-console-services service for your changes to take effect. To reload the service run:

sudo service pe-console-services
						reload

To use a certificate in a curl command, include the allowed certificate name (which must match a name in the rbac-certificate-allowlist file) and, if necessary, the private key. For example:

cert="$(puppet config print hostcert)"
cacert="$(puppet config print localcacert)"
key="$(puppet config print hostprivkey)"
uri="https://$(puppet config print server):4433/activity-api/v1/events"

curl --cert "$cert" --cacert "$cacert" --key "$key" "$uri"

Tip: You do not need to use an agent certificate for authentication. You can use the puppet cert generate command to create a certificate to use specifically with the activity service API.