# Updates the password for a specific user account

`PUT /api/users/{username}/password`

- **Products:** Operator (`FOH`), `LEGACY` (any one of these products, not all)
- **Features:** Front of House Generic Access (`FOHGENERIC`)

HTML version: [Updates the password for a specific user account](https://support.gladstonesoftware.cloud/reference/users/updates-the-password-for-a-specific-user-account)

## Overview

Sets a new password on a staff (back-office) user account. Returns `204 No Content` with no body.

This is an administrative reset, not a self-service change: it does not ask for the current password, and any caller authorised for this route can set the password of any user in the tenant. Treat the route as privileged and log its use on your side.

Two rules will reject a password that looks perfectly reasonable, and both are tenant configuration rather than fixed policy:

- **Complexity.** The password is matched against a regular expression chosen by the tenant's `PasswordComplexity` setting (`low`, `medium` or `high`). This is checked first, before the user is even looked up. A failure returns `400` whose body is a JSON object `{"errorMessage": "…", "isPasswordError": true}` carrying the tenant's own wording — not a plain string like the other `400`s on this endpoint. Surface that message to the user rather than writing your own rule; you cannot read the pattern through this API.
- **Reuse.** The password is compared against the account's five most recent passwords and rejected with `400` and `Password has already been used` if it matches any of them. The new password is then added to that history, so a caller cannot flip an account between two passwords.

On [ObjectId-role tenants](retrieves-all-administrative-users-configured-in-the-system.md), a successful change also clears the account's forced-password-reset flag, so you do not need to call [Updates a user's password reset flag for account security management](updates-a-users-password-reset-flag-for-account-security-management.md) afterwards. On numeric-role tenants, that flag is left as it was, and a user whose flag is still set will be prompted to reset again at their next sign-in.

## Endpoint

`PUT {base_url}/api/users/{username}/password`

`{base_url}` is the environment URL issued to your integration. See [Authenticating with Gladstone APIs](../../guides/authenticating-with-gladstone-apis.md).

## Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `username` | string | Yes | The sign-in name of the account whose password is being set, as returned in `[].username` by [Retrieves all administrative users configured in the system](retrieves-all-administrative-users-configured-in-the-system.md). Matched exactly. Note that the complexity check runs before this is resolved, so an invalid password returns `400` even when the username does not exist. |

## Request body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `newPassword` | string | Yes | The replacement password, sent in plain text over TLS and stored hashed. Rejected with `400` if blank or longer than 128 characters. It must match the tenant's configured complexity pattern, and must not match any of the account's five most recent passwords. There is no confirmation field and no current-password field — whatever you send here becomes the account's password immediately, and the previous one cannot be recovered. |

## Sample request

```bash title="cURL"
curl -X PUT '{base_url}/api/users/{username}/password' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "newPassword": "string"
}'
```

## Errors

| Status | Meaning | When |
|--------|---------|------|
| `400` | Bad request | `newPassword` does not match the tenant's configured complexity pattern. The body is a JSON object `{"errorMessage": "…", "isPasswordError": true}` carrying the tenant's own message, not a plain string. Checked before the username is resolved. |
| `400` | Bad request | `newPassword` matches one of the account's five most recent passwords: `Password has already been used`. |
| `400` | Bad request | `newPassword` is blank or longer than 128 characters. |
| `404` | Not found | No account exists with that username: `SQL user with id:{username} was not found.` on numeric-role tenants, or `User {username} cannot be found when calling UpdateUserPassword` on ObjectId-role tenants, where the account must be fully set up. |
| `422` | Unprocessable entity | The tenant's password security configuration is incomplete or inconsistent — either required settings are missing (`The security level configurations: [...] were not found`) or `PasswordComplexity` holds a value other than `low`, `medium` or `high` (`The configuration for the password complexity: {value} does not have a matching regex or error message`). This is a tenant setup fault, not something the caller can fix by changing the request. |
| `500` | Internal server error | Any other unexpected server-side failure, including a failure partway through saving the new password, which can leave the change only partly applied. Returned with no body. |