Password endpoints
Sections
When local users forget passwords or lock themselves out
of PE by attempting to log in with incorrect credentials too many times, you must generate a
password reset token for them. The password
endpoints enable you to generate password reset tokens for a specific local user or with a
token that contains a temporary password in the body.
failed-attempts-lockout parameter.POST /users/:sid/password/reset
Generates a single-use password reset token for the specified local user.
The generated token can be used to reset the password only one time and it has a
limited lifetime. The lifetime is based on a configuration value puppet_enterprise::profile::console::rbac_password_reset_expiration
(number of hours). The default value is 24 hours. Authentication is required.
This token is to be given to the appropriate user for use with the
/auth/reset endpoint.
Response format
AOsATK53e_M2Ltfy_qum5mAjlO-GAXs3c82k7P1kf1_yCopied!Error responses
Returns a 403 Forbidden response if the user does not have permissions to create a reset path for the specified user, or if the user is a remote user.
Returns a 404 Not Found response if a user with the given identifier does not exist.
POST /auth/reset
Resets a local user's password using a one-time token
obtained via the /users/:sid/password/reset
endpoint, with the new password in the body. No authentication is required to use this
endpoint.
Request format
The appropriate user is identified in the payload of the token. This endpoint does not establish a valid logged-in session for the user.
For example:
{"token": "text of token goes here",
"password":"someotherpassword"}Copied!Response format
Returns a 200 OK response if the token is valid and the password has been successfully changed.
Error responses
Returns a 403 Permission Denied response if the token has already been used or is invalid.
PUT /users/current/password
Changes the password for the current local user. A payload containing the current password must be provided. Authentication is required.
Request format
The current and new passwords must both be included.
For example:
{"current_password": "somepassword",
"password": "someotherpassword"}Copied!Response format
Returns a 200 OK response if the password has been successfully changed.
Error responses
Returns a 403 Forbidden response if the user is a remote
user, or if current_password doesn't match the
current password stored for the user. The body of the response includes a message that specifies
the cause of the failure.
POST /command/validate-password
Check whether a password is valid.
Request format
| Key | Definition |
|---|---|
password |
String. A password to validate for compliance. |
reset-token |
Optional string. A password reset token used to identify the user for password validation. It can only be specified when using certificate authentication. |
{ "password": <password here>}Copied!{
"password": <password here>,
"reset-token": <reset token>
}Copied!Response format
{"valid": true}Copied!{"valid": false,
"failures": [
{
"rule-identifier": "letters-required",
"friendly-error": "Passwords must have at least 2 letters."
}
]
}Copied!If the request has formatting issues, a "400" response is returned.
POST /command/validate-login
Validate whether a username/login is valid.
Request format
| Key | Definition |
|---|---|
login |
String. The username to validate for compliance. |
Response format
{ "valid": true }Copied! {
"valid": false,
"failures": [
{
"rule-identifier": "login-minimum-length",
"friendly-error": "The login for the user must be a minimum of one character."
}
]
}Copied!