Forming RBAC API requests
Token-based authentication is required to access the RBAC API v1 and v2 endpoints. You can authenticate requests by using either user authentication tokens or allowed certificates.
By default, the RBAC service listens on port 4433. All endpoints are
relative to the
/rbac-api/ path. So, for
example, the full URL for the
endpoint on localhost is
Authenticating using tokens
Insert a user authentication token in an RBAC API request.
- Generate a token:
Print the token and copy it:
- Save the token as an environment variable:
export TOKEN=<PASTE THE TOKEN HERE>
- Include the token variable in your API request:
auth_header="X-Authentication: $(puppet-access show)" uri="https://$(puppet config print server):4433/rbac-api/v1/users/current" curl --insecure --header "$auth_header" "$uri"
See Usage notes for curl examples for information about forming curl commands.
The example above uses the X-Authentication header to supply the token information. In some cases, such as GitHub webhooks, you might need to supply the token in a token parameter. To supply the token in a token parameter, specify the request as follows:
uri="https://$(puppet config print server):4433/rbac-api/v1/users/current?token=$(puppet-access show)" curl --insecure "$uri"
Authenticating using an allowed certificate
You can also authenticate requests using a certificate listed in RBAC's certificate
allowlist, located at
that if you edit this file, you must reload the
sudo service pe-console-services reload) for your changes
to take effect.
Attach the certificate using the command line, as demonstrated in the example curl query
below. You must have the allowed certificate name (which must match a name in the
and the private key to run the script.
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"
You do not need to use an agent certificate for authentication. You can use
puppet cert generate to create a new certificate specifically for
use with the API.
Content-type headers in the RBAC API
RBAC accepts only JSON payloads in PUT and POST requests.
If a payload is provided, it is important to specify that the content
is in JSON format. Thus, all
POST requests with non-empty bodies
should have the
Content-Type header set