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)

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 400s 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, 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 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.

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. 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

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.

This page as markdown · All pages · llms.txt