Skip to main content

Replace a user

PUT 
/users/:username

Overwrites a user's profile with the body you send.

This is a replace, not a patch, and there is no merge with what is already stored. Every field you leave out is written as its empty value: email, firstName and lastName become empty strings, and enabled becomes false, which disables the account. A one-field "update" of a first name will silently lock the user out. Fetch GET /users/{username} first and send the whole object back, including "enabled": true.

attributes is the single exception, and it breaks the rule in the other direction. Omitting it does not clear the stored attributes; they are left exactly as they were. Only an explicit "attributes": {} clears them. So the destructive partial update above wipes every field it omits except this one, and a caller who means to remove a user's attributes has to say so rather than leave the key out.

username in the body renames the user, on a realm that allows it; the {username} in the path only says who to update. After a rename the path value no longer resolves, and the username echoed back in the response is the one from the path, so it is already stale by the time you read it. A rename onto a name that is already taken comes back as a 500, not a 409.

Whether renaming is possible at all is a property of your deployment, not of this API. The directory behind Prism carries a configuration setting that controls whether a username may be changed once it is set, and that setting, not anything in this API, decides the outcome. Where it is turned off the username is read-only, and a body whose username differs from the path value fails with a 500 carrying error-user-attribute-read-only, with the user left completely untouched, so the other fields in that same body are not applied either. That error string is your only signal; read it as "this deployment does not allow renaming" rather than as a fault in the request.

Prism neither reports nor changes that setting, and this API gives you no way to read it. Ask whoever administers your Prism deployment whether usernames can be changed; failing that, the only way to find out is to try it against a test user. Where renaming is disabled, send the existing username back unchanged on every PUT.

groups is accepted in the body and ignored. Updating a user never changes their group membership.

Unlike POST /users, this operation validates nothing. The character rules described on the request fields are enforced on create only, so a value POST refuses is stored here without complaint. The only 400 this operation returns is for a body that is not valid JSON.

The response does not include the updated user. Re-fetch with GET /users/{username} if you need to see the result.

Request​

Responses​

The user was replaced. The body is a two-key acknowledgement, not the updated user.