Skip to content

Reset a user's password

POST
/admin/users/{ref}/password-reset

Gives a user a new, randomly generated password and returns it to you once, so you can pass it on yourself. Their old password stops working, and the server tries to end their sessions.

The password is 16 random characters (letters, digits, - and _). Nothing makes it single-use or makes it expire, the user isn’t asked to change it at the next sign-in, and it isn’t checked against the password policy. The server stores only its hash. No email is sent, and the user’s API tokens keep working.

Any user can be reset, including administrators and accounts that had no password. If recording the password history or ending the sessions fails, the reset still succeeds and the error is only logged. The reset is recorded in the audit log as user.password_reset with your optional reason, on a best-effort basis. You need users.password.reset (system.admin also works).

ref
required
integer format: int64
object
reason

Why you’re resetting the password. Recorded in the audit log. Optional.

string
<= 500 characters

The new password, shown this once.

object
temporary_password
required

The new password. It appears only in this response: the server keeps just its hash, and no endpoint returns it again. Treat the response as a secret.

string
generated_at
required
string format: date-time

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

Authenticated but missing required capabilities

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Resource not found

object
error
required

Human-readable error summary

string
Example
the request could not be completed

Unexpected server error

object
error
required

Human-readable error summary

string
Example
the request could not be completed