Reset password for a user in this organization

POST

/api/v1/organizations/{id}/users/{userId}/reset-password

curl --request POST \
  --url http://localhost:3000/api/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/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" }'

• Development
• Production

Triggers a password reset for a user that is a member of this organization. Allowed for tenant admins (USERS_WRITE) and superadmins. Refuses self-reset (use the profile security page instead) and reset for inactive users.

delivery: 'email' (the default) is NON-DESTRUCTIVE: the existing password keeps working and the user receives a Keycloak UPDATE_PASSWORD email carrying the reset form — only the user sets the new password. Delivery preconditions are 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 and returns temporaryPassword exactly once.

Authorizations

• api-key
• bearer

Parameters

Path Parameters

id

required

string format: uuid

Organization UUID

userId

required

string format: uuid

User UUID

Request Body^required

Media typeapplication/json

object

delivery

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.

string

default: email

Allowed values: email display

password

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.

string

sendEmail

DEPRECATED (FM-862): ignored. Use delivery instead — email delivery is now the default and is non-destructive.

boolean

reason

Reason for resetting the password

string

Responses

200

Password reset triggered

Media typeapplication/json

object

success

required

Whether the password reset itself succeeded

boolean

delivery

required

The delivery mode that was applied.

string

Allowed values: email display

temporaryPassword

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.

string

mustChangePassword

required

User must change password on next login

boolean

emailSent

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

boolean

emailError

Why the email was not sent, when emailSent is false (e.g. ‘no-keycloak-account’, ‘keycloak-sync-disabled’, ‘keycloak-send-failed’).

string

Example

{
  "delivery": "email"
}

400

Self-reset attempted or user is not active

401

Unauthorized

403

Forbidden — caller lacks USERS_WRITE in this org

404

User is not a member of this organization

409

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.