Change Logon Password
The Change Logon Password operation changes the logon password during a logon sequence for an MFA-enabled user.
HTTP method and URI
POST /api/sessions/operations/change-logon-password
Request body contents
The request body is expected to contain a JSON object with the following fields:
Field name | Type | Rqd/Opt | Description |
---|---|---|---|
current-password | String | Required | The password used to authenticate the HMC user associated with the partially-authenticated API session identified by the X-API-Session HTTP request header. |
new-password | String | Required | A new password to be established for the user. The required length and valid characters are determined by the password policy in effect for the user ID. |
Response body contents
On successful completion, the response body contains a JSON object with the same format as the response body for a Logon operation that completed with HTTP status code 200 (OK). See the Logon Response body contents.
Description
This operation changes the password used to authenticate the user associated with a partially-authenticated API session when that user's password has expired. The API session is identified by the X-API-Session HTTP request header. If the new password does not meet the requirements of the password policy in effect for this user or if the password is not changeable because it is managed by an external authentication mechanism, the request fails with status code 400 (Bad Request) and a reason code indicating the cause of the failure.
Upon successful completion the user's password is changed and this operation completes the authentication of a partially-authenticated API session created by a previous Logon operation that completed with HTTP status code 201 (Created) or HTTP status code 409 (Conflict) with reason code 50 or 51. That partially-authenticated API session's ID must be specified on the X-API-Session request header.
The request body is validated against the schema described in Request body contents. If the request body is not valid, status code 400 (Bad Request) is returned with a reason code indicating the validation error encountered. If the X-API-Session request header does not identify a partially-authenticated session, HTTP status code 400 (Bad Request) is returned. If the specified current password is not correct, HTTP status code 403 (Forbidden) is returned.
If the operation does not complete with status code 200 (OK), the partially-authenticated session identified by the X-API-Session HTTP request header is destroyed.
Authorization requirements
The request must contain the session ID of a partially-authenticated API session for a user whose logon password has expired and the current password for the user associated with that API session.
HTTP status and reason codes
On success, HTTP status code 200 (OK) is returned, the response body is provided as described in Response body contents.
The following HTTP status codes are returned for the indicated errors, and the response body is a standard error response body providing the reason code indicated and associated error message.
HTTP error status code | Reason code | Description |
---|---|---|
400 (Bad Request) | Various | Errors were detected during common request validation. See Common request validation reason codes for a list of the possible reason codes. |
44 | The new password does not conform to the requirements of the password policy in effect for this user. | |
46 | The X-API-Session request header does not identify a partially-authenticated session that requires a logon password change. | |
403 (Forbidden) | 0 | Login failed. Try the operation again. If the problem persists, contact your security administrator. |
Additional standard status and reason codes can be returned, as described in Invoking API operations.
Example HTTP interaction
Usage notes
See the usage notes for the Logon operation for more information on using multi-factor authentication with the APIs.