Updates the details and settings for a specific administrative user

PUT /api/users/{username}

Products: Operator (FOH)
Features: Front of House Generic Access (FOHGENERIC)

Overview

Replaces the profile, site assignment, role and account-status flags of one staff (back-office) user. Returns 204 No Content with no body.

This is a full replacement, not a patch. Every field you send is written, and the required fields must be present on every call — so read the account first with Retrieves detailed information for a specific administrative user and send back the current values of everything you are not changing, or you will silently blank them.

Passwords are not changed here. Use Updates the password for a specific user account for that, and Updates a user's password reset flag for account security management if you only want to force a reset — although isPasswordResetFlagSet on this request writes the same flag.

Two side effects are worth knowing before you call. Changing isLocked from true to false also resets failedLoginAttemptsCount to 0, which is how you release a locked-out user. And preferredSiteId is not a field of the account: it is written through as the user preference named PreferredSiteId, the same store the endpoints under /api/users/preference/{preferenceId} read and write.

Endpoint

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

{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 to update. It must be character-for-character identical to `username` in the request body, or the call fails with `400` and `The username in the request: {username} and the one in route: {username} do not match`. This endpoint cannot rename an account.

Request body

Field	Type	Required	Description
`username`	string	Yes	Must repeat the `username` from the path exactly; the two are compared before anything else and a mismatch fails with `400`. It is not a new name for the account — renaming is not supported here. Rejected with `400` if blank or longer than 8 characters.
`firstName`	string	Yes	The user's given name. Used to rebuild `displayName` when you send that blank. Rejected with `400` if blank or longer than 25 characters.
`lastName`	string	Yes	The user's family name. Used to rebuild `displayName` when you send that blank. Rejected with `400` if blank or longer than 25 characters.
`displayName`	string	No	The name shown to other staff in the back office. Rejected with `400` above 50 characters. Sending it blank or omitting it does not leave the current value alone — it resets the stored name to `"{firstName} {lastName}"`.
`email`	string	No	The account's contact address. Rejected with `400` above 255 characters, and — when non-empty — validated against an RFC-style address pattern, failing with `The email in the request: {email} is invalid`. Send it blank or omit it to clear the stored address; the format check is skipped in that case.
`cardId`	string	No	The identifier on the physical staff card this user presents at a reader or till. Rejected with `400` above 50 characters. Omitting it clears the stored card, so resend the current value if the user still has a card.
`siteGroupId`	string	Yes	The site group the user belongs to, taken from `id` in Retrieves all site groups with their configuration details. It must resolve to an existing group or the call fails with `404` — note `404`, not `400` — and `The site group in the request: {siteGroupId} could not be found`. It also constrains `preferredSiteId`. Rejected with `400` if blank.
`preferredSiteId`	string	Yes	The site the user works at by default. It must be one of the sites inside `siteGroupId`, compared case-insensitively, or the call fails with `400` and `The preferred site Id: {preferredSiteId} is not contained in the given site group`. Written through as the user preference named `PreferredSiteId` rather than onto the account. Rejected with `400` if blank.
`avatarId`	string	No	The profile image the back office shows for this user. Rejected with `400` above 25 characters. On ObjectId-role tenants, sending it blank resets the saved value to the literal `default`. On numeric-role tenants it is not saved at all.
`isActive`	boolean	Yes	Whether the account may be used. Send `false` to suspend a user while keeping their record and username — a reversible alternative to Permanently deletes a user account from the system. Because the field is a non-nullable boolean, omitting it reads as `false` and deactivates the account, so always send it explicitly.
`isLocked`	boolean	No	Whether the account is locked out of signing in. Sending `false` for a user who was locked also resets `failedLoginAttemptsCount` to `0`, which is how you release a user locked out by repeated failed sign-ins. Omitting it reads as `false` and therefore unlocks the account.
`isPasswordResetFlagSet`	boolean	No	Whether the user must set a new password at their next sign-in. Writes the same flag as Updates a user's password reset flag for account security management. Omitting it reads as `false` and clears any pending forced reset, so resend the current value if you are not deliberately changing it.
`roleId`	string	No	The permission role to grant, as a 24-character hexadecimal string. Validated only on ObjectId-role tenants, where a value of the wrong length fails with `400` and `The role: {roleId} is invalid. It must be exactly 24 characters long`, and a well-formed value matching no role fails with `404` and `The role for ID: {roleId} could not be found`. Sending an empty string `""` removes the user's role; omitting the field or sending `null` leaves the current role unchanged — the two are not equivalent. On numeric-role tenants this endpoint does not change the user's role.

Sample request

cURL

curl -X PUT '{base_url}/api/users/{username}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "username": "string",
  "firstName": "string",
  "lastName": "string",
  "displayName": "string",
  "email": "member@example.com",
  "cardId": "string",
  "siteGroupId": "string",
  "preferredSiteId": "string",
  "avatarId": "string",
  "isActive": true,
  "isLocked": true,
  "isPasswordResetFlagSet": true,
  "roleId": "string"
}'

Errors

Status	Meaning	When
`400`	Bad request	`username` in the body does not match the one in the path: `The username in the request: {username} and the one in route: {username} do not match`. Checked before every other rule.
`400`	Bad request	A required field is blank, or a field exceeds its maximum length — for example `Username cannot be more than 8 characters`.
`400`	Bad request	`email` is non-empty but not a valid address: `The email in the request: {email} is invalid`.
`400`	Bad request	`preferredSiteId` is not one of the sites in `siteGroupId`: `The preferred site Id: {preferredSiteId} is not contained in the given site group`.
`400`	Bad request	On ObjectId-role tenants only, `roleId` is not exactly 24 characters: `The role: {roleId} is invalid. It must be exactly 24 characters long`.
`404`	Not found	`siteGroupId` does not resolve to a site group: `The site group in the request: {siteGroupId} could not be found`. This is a request-data problem returned as a `404`, not a `400`.
`404`	Not found	On ObjectId-role tenants only, `roleId` is well-formed but matches no role: `The role for ID: {roleId} could not be found`.
`404`	Not found	No account exists with that username: `Failed to find the user with username: {username} in SQL database`, or `User {username} cannot be found when calling Update` on ObjectId-role tenants, where the account must be fully set up.
`500`	Internal server error	Any unexpected server-side failure, including a conflict raised when a value on the account cannot be changed — that case is not translated into a `409` by this endpoint and surfaces as a bodyless `500`. Also returned when the two halves of the update fail to complete together.

This page as markdown · All pages · llms.txt