Tokens endpoints

Tokens endpoints keys

These keys are used with the tokens endpoints.


Key	Description
`login`	The user's login for the PE console. Only valid with POST /auth/token.
`password`	The user's password for the PE console. Only valid with POST /auth/token.
`lifetime`	Used to Set a token-specific lifetime. If omitted, the default token lifetime is used.
`description`	Optional description of the token.
`client`	Optional description about the client making the token request, such as `PE console`.
`label`	Optional key used to Set a token-specific label.

POST /auth/token

Generate an authorization token for a user identified by login and password. This token can be used to authenticate requests to Puppet Enterprise (PE) services, such as by using an X-Authentication header or a token query parameter in an API request.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body must be a JSON object identifying the user you want to create a token for and optional token settings. You must supply the login and password keys. Other keys, such as the lifetime or label, are optional. For descriptions of keys, refer to Tokens endpoints keys.

For example:

type_header='Content-Type: application/json'
cacert="$(puppet config print cacert)"
uri="https://$(puppet config print server):4433/rbac-api/v1/auth/token"
data='{"login": "<USER>", 
       "password": "<PASSWORD>", 
       "lifetime": "4h", 
       "label": "four-hour token"}'

curl --header "$type_header" –cacert "$cacert" --request POST "$uri" --data "$data"

Tip: This route is intended to require zero authentication to generate the key. While HTTPS is still required (unless PE is explicitly configured to permit HTTP), neither an allowed cert nor a session cookie is required to post to this endpoint.

The --cacert <FILE> argument in the above curl command specifies an authentication certificate as described in Forming RBAC API requests. Alternatively, at your discretion and understanding of the risks, you could use the -k or --insecure flag to turn off SSL verification of the RBAC server so that you can use the HTTPS protocol without providing a CA cert. If you do not provide one of these options in your curl request, you might get an error or warning about not being able to verify the RBAC server.

Here is an additional curl request example:

curl --insecure -X POST 'https://$(puppet config print server):4433/rbac-api/v1/auth/token' \
-H "Content-type: application/json" \
-d '{"login": "test",
     "password": "Test123!",
     "lifetime": "4m",
     "label": "personal workstation token"}'

Response format

If the credentials are valid and the specified user is not revoked, the endpoint returns 200 OK and the new token, such as:

{"token":"0QX-WR3kgP0R9C2dA0I2nfnp0QgAT95_xH3iylBhqroA"}

From here, you can save the token, as described in Generate a token using the RBAC API.

Error responses

Returns 401 Unauthenticated if the credentials are invalid or the user is revoked.

Returns 400 Malformed if something is wrong with the request body.

For other errors, refer to RBAC service errors.

POST /tokens

Create a token for the authenticated user. Doesn't allow certificate authentication.

Request format

When Forming RBAC API requests to this endpoint, the content type is application/json. The body can be a JSON object identifying token settings, such as the lifetime or label. For descriptions of keys, refer to Tokens endpoints keys.

For example:

curl -X POST 'https://$(puppet config print server):4433/rbac-api/v1/tokens' \
-H "X-Authentication:$(puppet-access show)" \
-H "Content-type: application/json" \
-d '{"lifetime": "1y", 
     "description": "A token to be used with joy and care.",
     "client": "PE console"}'

Response format

If the supplied authentication is valid, not expired, and the attached user is not revoked, the endpoint returns 200 OK and the new token, such as:

{"token":"0QX-WR3kgP0R9C2dA0I2nfnp0QgAT95_xH3iylBhqroA"}

Error responses are similar to the POST /auth/token error responses.