Docs Grey arrow pointing right Puppet Enterprise Grey arrow pointing right Managing access Grey arrow pointing right RBAC API Grey arrow pointing right RBAC API v1 Grey arrow pointing right Token endpoints Grey arrow pointing right POST /auth/token Grey arrow pointing right

POST /auth/token

Sections

Generates an access token for the user whose login information is POSTed. This token can then be used to authenticate requests to PE services using either the X-Authentication header or the token query parameter.

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

Request format

Accepts a JSON object or curl command with the user's login and password information. The token's lifetime, a user-specified label, and additional metadata can be added, but are not required.

An example JSON request:

{"login": "jeanjackson@example.com",
 "password": "1234",
 "lifetime": "4m",
 "label": "personal workstation token"}Copied!

An example curl command request: 

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"Copied!

See Usage notes for curl examples for information about forming curl commands.

The various parts of this curl command request are explained as follows:

  • --header 'Content-Type: application/json': sets the Content-Type header to application/json, which indicates to RBAC that the data being sent is in JSON format.
  • --cacert [FILE]: Specifies a CA certificate as described in Forming requests for the node classifier. Alternatively, you could use the --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, curl complains about not being able to verify the RBAC server.
    Note: The --insecure flag is shown as an example only. You should use your own discretion when choosing the appropriate server verification method for the tool that you are using.
  • --request POST: This is an HTTP POST request to provide your login information to the RBAC service.
  • https://<HOSTNAME>:<PORT>/rbac-api/v1/auth/token: Sends the request to the token endpoint. For HOSTNAME, provide the FQDN of the server that is hosting the PE console service. If you are making the call from the console server, you can use "localhost." For PORT, provide the port that the PE services (node classifier service, RBAC service, and activity service) listen on. The default port is 4433
  • --data '{"login": "<USER>", "password": "<PASSWORD>", "lifetime": "4h", "label": "four-hour token"}': Provide the user name and password that you use to log in to the PE console. Optionally, set the token's lifetime and label.

Response format

Returns a 200 OK response if the credentials are good and the user is not revoked, along with a token.

For example:

{"token": "asd0u0=2jdijasodj-w0duwdhjashd,kjsahdasoi0d9hw0hduashd0a9wdy0whdkaudhaksdhc9chakdh92..."}Copied!

Error responses

Returns a 401 Unauthenticated response if the credentials are bad or the user is revoked.

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

Was this page helpful?