Forming RBAC API requests
The role-based access control (RBAC) API accepts well-formed HTTPS requests. Token-based authentication is required for most endpoints. You can use either user authentication tokens or allowed certificates to authenticate requests.
URIpath following the pattern:
DNS: Your PE console host's DNS name. You can use
localhost, manually enter the DNS name, or use a
puppetcommand (as explained in Using example commands).
v2, depending on the endpoint.
ENDPOINT: One or more sections specifying the endpoint, such as
roles. Some endpoints require multiple sections, such as the POST /command/roles/add-users endpoint.
https://$(puppet config print server):4433/rbac-api/v1/users https://localhost:4433/rbac-api/v1/users https://puppet.example.dns:4433/rbac-api/v1/users
To form a complete curl command, you need to provide appropriate curl arguments, authentication, and you might need to supply the content type and/or 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.
For most RBAC API endpoints, you must authenticate your requests with user authentication tokens. For instructions on generating, configuring, revoking, and deleting authentication tokens in PE, go to Token-based authentication.
puppet-access show, such as:
auth_header="X-Authentication: $(puppet-access show)" uri="https://$(puppet config print server):4433/rbac-api/v1/users" curl --header "$auth_header" "$uri"
auth_header="X-Authentication: <TOKEN>" uri="https://$(puppet config print server):4433/rbac-api/v1/users" curl --header "$auth_header" "$uri"
URIpath, such as:
https://$(puppet config print server):4433/rbac-api/v1/users/current?token=$(puppet-access show) https://$(puppet config print server):4433/rbac-api/v1/users/current?token=<TOKEN>
Allowed certificate authentication
allowlist, which is located at:
rbac-certificate-allowlistfile, you must reload the
pe-console-servicesservice for your changes to take effect. To reload the service run:
sudo service pe-console-services reload
rbac-certificate-allowlistfile) 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/rbac-api/v1/users/current" curl --cert "$cert" --cacert "$cacert" --key "$key" "$uri"
puppet cert generatecommand to create a certificate to use specifically with the RBAC API.
Payloads that use JSON objects for permissions must represent each of the three
components: Type (
object_type), permission (
action), and object (
instance), as described in Structure of user permissions. In
RBAC API requests, you must use the system names (not the display names) described in
Reference: User permissions and names.
The RBAC API accepts only JSON payloads in
If you provide a JSON payload, you must specify that the content is in JSON format. Thus,
POST requests with non-empty bodies must
Content-Type header set to