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.

Table 1. Change Logon Password: HTTP status and reason codes
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

Figure 1. Change Logon Password: Request
POST /api/sessions/operations/change-logon-password HTTP/1.1
x-api-session: 4uyp0d2o7q0495p4ktmw9mt4ef4w2owsrqjjgch7rbhds17u73
content-type: application/json
content-length: 60
{
   "current-password":"12345678",
   "new-password":"87654321"
}
Figure 2. Change Logon Password: Response
200 OK
server: Hardware management console API web server / 2.0
cache-control: no-cache
date: Mon, 30 Sep 2019 19:51:25 GMT
x-api-session: 18l8cbyrsndoabvzdy1gq6oscqd77hjmsyy4j4ezvf0tptf5vp
content-type: application/json
content-length: 301
{
  "api-major-version":3,
  "api-minor-version":2,
  "api-session":"18l8cbyrsndoabvzdy1gq6oscqd77hjmsyy4j4ezvf0tptf5vp",
  "job-notification-topic":"apiuser1.12job",
  "notification-topic":"apiuser1.12",
  "password-expires":12,
  "session-credential":"2q2dbw5xbrzgjzcnn1r13shuv3k00vcy1gjhqtfg2fogpor6ii"
}

Usage notes

See the usage notes for the Logon operation for more information on using multi-factor authentication with the APIs.