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.

RBAC API requests must include a URI path following the pattern:
https://<DNS>:4433/rbac-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: One or more sections specifying the endpoint, such as users or roles. Some endpoints require multiple sections, such as the POST /command/roles/add-users endpoint.
Tip: The RBAC service listens on port 4433 by default. If you change the RBAC service's port, you'll need to change the port in your API calls.
For example, you could use any of these paths to call the GET /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.

Token authentication

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.

To use a token in an RBAC API request, you can use 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"
Or you can use the actual token, such as:
auth_header="X-Authentication: <TOKEN>"
uri="https://$(puppet config print server):4433/rbac-api/v1/users"

curl --header "$auth_header" "$uri"
For some endpoints, you might append the token (or token variable) directly to the URI path, 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>
CAUTION: Tokens supplied as query parameters might be recorded in server access logs.

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/rbac-api/v1/users/current"

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 RBAC API.

Permissions objects

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.

RBAC API Content-Type headers

The RBAC API accepts only JSON payloads in PUT and POST requests.

If you provide a JSON payload, you must specify that the content is in JSON format. Thus, all PUT and POST requests with non-empty bodies must have the Content-Type header set to application/json.