{
  "schema_version": 2,
  "id": "operate/rs/references/rest-api/requests/users/password",
  "title": "User password requests",
  "url": "https://redis.io/docs/latest/operate/rs/references/rest-api/requests/users/password/",
  "summary": "User password requests",
  "tags": [
    "docs",
    "operate",
    "rs"
  ],
  "last_updated": "2025-06-30T12:38:51-05:00",
  "page_type": "content",
  "content_hash": "484e8b62e6cc68c49d5efcc7b71ca2d4b7a021d393a3e340142968b63d567de1",
  "sections": [
    {
      "id": "overview",
      "title": "Overview",
      "role": "overview",
      "text": "| Method                     | Path                 | Description                 |\n|----------------------------|----------------------|-----------------------------|\n| [PUT](#update-password)    | `/v1/users/password` | Replace passwords |\n| [POST](#add-password)      | `/v1/users/password` | Add a new password          |\n| [DELETE](#delete-password) | `/v1/users/password` | Delete a password           |"
    },
    {
      "id": "update-password",
      "title": "Update password",
      "role": "content",
      "text": "PUT /v1/users/password\n    \nReplaces the password list of the specified user with a single new password. If a `username` is not provided in the JSON request body, it replaces the password list of the authenticated user making this request instead."
    },
    {
      "id": "put-request",
      "title": "Request",
      "role": "content",
      "text": "#### Example HTTP request\n\n    PUT /v1/users/password\n\n#### Example JSON body\n\n  [code example]\n\n#### Request headers\n| Key    | Value            | Description         |\n|--------|------------------|---------------------|\n| Host   | cnm.cluster.fqdn | Domain name         |\n| Accept | application/json | Accepted media type |\n\n#### Request body\n\nThe request must contain a JSON object with the following fields:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| username     | string | (Optional) The username of the affected user. If missing, defaults to the authenticated user. |\n| new_password | string | The new password (required) |"
    },
    {
      "id": "put-response",
      "title": "Response",
      "role": "returns",
      "text": "Returns a status code to indicate password update success or failure."
    },
    {
      "id": "put-error-codes",
      "title": "Error codes",
      "role": "errors",
      "text": "When errors are reported, the server may return a JSON object with\n`error_code` and `message` fields that provide additional information.\nThe following are possible `error_code` values:\n\n| Code | Description |\n|------|-------------|\n| password_not_complex | The given password is not complex enough (Only work when the password_complexity feature is enabled). |\n| new_password_same_as_current | The given new password is identical to one of the already existing passwords. |\n| user_not_exist | User does not exist. |\n| unauthorized_action | Updating another user's password is acceptable by an admin user only. |"
    },
    {
      "id": "put-status-codes",
      "title": "Status codes",
      "role": "content",
      "text": "| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, password changed. |\n| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing parameters. |\n| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | The user is unauthorized. |\n| [403 Forbidden](https://www.rfc-editor.org/rfc/rfc9110.html#name-403-forbidden) | Insufficient privileges. |\n| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | User not found. |"
    },
    {
      "id": "add-password",
      "title": "Add password",
      "role": "content",
      "text": "POST /v1/users/password\n\nAdds a new password to the specified user's password list. If a `username` is not provided in the JSON request body, it adds the password to the password list of the authenticated user making this request instead."
    },
    {
      "id": "post-request",
      "title": "Request",
      "role": "content",
      "text": "#### Example HTTP request\n\n    POST /v1/users/password\n\n#### Example JSON body\n\n  [code example]\n\n#### Request headers\n| Key    | Value            | Description         |\n|--------|------------------|---------------------|\n| Host   | cnm.cluster.fqdn | Domain name         |\n| Accept | application/json | Accepted media type |\n\n#### Request body\n\nThe request must contain a JSON object with the following fields:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| username     | string | (Optional) The username of the affected user. If missing, defaults to the authenticated user. |\n| new_password | string | New password to add (required) |"
    },
    {
      "id": "post-response",
      "title": "Response",
      "role": "returns",
      "text": "Returns a status code to indicate password creation success or failure. If an error occurs, the response body may include a more specific error code and message."
    },
    {
      "id": "post-error-codes",
      "title": "Error codes",
      "role": "errors",
      "text": "When errors are reported, the server may return a JSON object with\n`error_code` and `message` fields that provide additional information.\nThe following are possible `error_code` values:\n\n| Code | Description |\n|------|-------------|\n| password_not_complex | The given password is not complex enough (Only work when the password_complexity feature is enabled). |\n| new_password_same_as_current | The given new password is identical to one of the already existing passwords. |\n| user_not_exist | User does not exist. |\n| unauthorized_action | Updating another user's password is acceptable by an admin user only. |"
    },
    {
      "id": "post-status-codes",
      "title": "Status codes",
      "role": "content",
      "text": "| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, new password was added to the list of valid passwords. |\n| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing parameters. |\n| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | The user is unauthorized. |\n| [403 Forbidden](https://www.rfc-editor.org/rfc/rfc9110.html#name-403-forbidden) | Insufficient privileges. |\n| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | User not found. |"
    },
    {
      "id": "delete-password",
      "title": "Delete password",
      "role": "content",
      "text": "DELETE /v1/users/password\n\nDeletes a password from the specified user's password list. If a `username` is not provided in the JSON request body, it deletes the password from the password list of the authenticated user making this request instead."
    },
    {
      "id": "delete-request",
      "title": "Request",
      "role": "content",
      "text": "#### Example HTTP request\n\n    DELETE /v1/users/password\n\n#### Example JSON body\n\n  [code example]\n\n#### Request headers\n| Key    | Value            | Description         |\n|--------|------------------|---------------------|\n| Host   | cnm.cluster.fqdn | Domain name         |\n| Accept | application/json | Accepted media type |\n\n#### Request body\n\nThe request must contain a JSON object with the following fields:\n\n| Field | Type | Description |\n|-------|------|-------------|\n| username | string | (Optional) The username of the affected user. If missing, defaults to the authenticated user. |\n| old_password | string | Existing password to be deleted (required) |"
    },
    {
      "id": "delete-response",
      "title": "Response",
      "role": "returns",
      "text": ""
    },
    {
      "id": "delete-error-codes",
      "title": "Error codes",
      "role": "errors",
      "text": "When errors are reported, the server may return a JSON object with\n`error_code` and `message` fields that provide additional information.\nThe following are possible `error_code` values:\n\n| Code | Description |\n|------|-------------|\n| cannot_delete_last_password | Cannot delete the last password of a user. |\n| user_not_exist | User does not exist. |\n| unauthorized_action | Updating another user's password is acceptable by an admin user only. |"
    },
    {
      "id": "delete-status-codes",
      "title": "Status codes",
      "role": "content",
      "text": "| Code | Description |\n|------|-------------|\n| [200 OK](https://www.rfc-editor.org/rfc/rfc9110.html#name-200-ok) | Success, new password was deleted from the list of valid passwords. |\n| [400 Bad Request](https://www.rfc-editor.org/rfc/rfc9110.html#name-400-bad-request) | Bad or missing parameters. |\n| [401 Unauthorized](https://www.rfc-editor.org/rfc/rfc9110.html#name-401-unauthorized) | The user is unauthorized. |\n| [403 Forbidden](https://www.rfc-editor.org/rfc/rfc9110.html#name-403-forbidden) | Insufficient privileges. |\n| [404 Not Found](https://www.rfc-editor.org/rfc/rfc9110.html#name-404-not-found) | User not found. |"
    }
  ],
  "examples": [
    {
      "id": "put-request-ex0",
      "language": "json",
      "code": "{\n      \"username\": \"The username of the affected user. If missing, default to the authenticated user.\",\n      \"new_password\": \"the new (single) password\"\n  }",
      "section_id": "put-request"
    },
    {
      "id": "post-request-ex0",
      "language": "json",
      "code": "{\n      \"username\": \"The username of the affected user. If missing, default to the authenticated user.\",\n      \"new_password\": \"a password to add\"\n  }",
      "section_id": "post-request"
    },
    {
      "id": "delete-request-ex0",
      "language": "json",
      "code": "{\n      \"username\": \"The username of the affected user. If missing, default to the authenticated user.\",\n      \"old_password\": \"an existing password to delete\"\n  }",
      "section_id": "delete-request"
    }
  ]
}