Reset user password
const url = 'http://localhost:3000/api/v1/users/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/reset-password';const options = { method: 'POST', headers: {'X-API-Key': '<X-API-Key>', 'Content-Type': 'application/json'}, body: '{"delivery":"email","password":"example","sendEmail":true,"reason":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:3000/api/v1/users/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/reset-password \ --header 'Content-Type: application/json' \ --header 'X-API-Key: <X-API-Key>' \ --data '{ "delivery": "email", "password": "example", "sendEmail": true, "reason": "example" }'Triggers a password reset for a user. Requires Super Admin privileges.
delivery: 'email' (the default) is NON-DESTRUCTIVE: the user’s existing password keeps working, Keycloak records an UPDATE_PASSWORD required action and emails them the reset form. Only the user can set the new password. Every delivery precondition is checked before anything is mutated, so a 409 no-delivery-channel means nothing was changed.
delivery: 'display' is the documented no-SMTP / air-gap recovery path only. It rotates the credential to a generated value, marks it temporary in Keycloak and returns it in temporaryPassword exactly once — it cannot be retrieved again.
Authorizations
Section titled “Authorizations ”Parameters
Section titled “ Parameters ”Path Parameters
Section titled “Path Parameters ”User UUID
Request Body required
Section titled “Request Body required ”object
How the reset reaches the user (FM-862). ‘email’ (the default) is non-destructive: the existing password keeps working and the user sets a new one from the emailed reset form. ‘display’ is the no-SMTP / air-gap recovery path only: it rotates the credential and returns the generated value once.
New password. Only honoured for delivery=‘display’; ignored for delivery=‘email’, where only the user may set the password. If omitted for ‘display’, a random password is generated and returned once.
DEPRECATED (FM-862): ignored. Use delivery instead — email delivery is now the default and is non-destructive.
Reason for resetting the password
Responses
Section titled “ Responses ”Password reset successfully
object
Whether the password reset itself succeeded
The delivery mode that was applied.
One-time generated password. Present ONLY for delivery=‘display’ when no explicit password was supplied. It is never stored and cannot be retrieved again — the caller must show it to the admin once. Absent for delivery=‘email’, which never rotates the credential.
User must change password on next login
Whether a reset email was actually sent. False when the user has no linked Keycloak account, Keycloak sync is disabled, or the send failed (FM-602 S2).
Why the email was not sent, when emailSent is false (e.g. ‘no-keycloak-account’, ‘keycloak-sync-disabled’, ‘keycloak-send-failed’).
Example
{ "delivery": "email"}Unauthorized
Forbidden - Super Admin required
User not found
No-delivery-channel — delivery=‘email’ was requested but the user has no linked Keycloak account or the realm has no SMTP server. Nothing was changed.