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.

This endpoint accepts only login and password credentials for authentication. Generating a token using SSO credentials is not supported.

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"

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 .