Issue a one-shot password for a user (admin helpdesk)

POST

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

• Local development behind nginx (port 8088 by default)

Admin/helpdesk password reset. Generates a cryptographically random temporary password, stores its hash, and returns the plaintext ONCE in the response so the admin can share it with the user out-of-band (chat / SMS / call). The user is expected to change it on next login; enforcement of “must change on first login” lands with the email-token reset flow in a follow-up phase. Audit captures the actor + reason; the plaintext password is never logged.

Authorizations

• cookieAuth
• bearerAuth

Parameters

Path Parameters

ref

required

integer format: int64

Request Body

object

reason

Admin-supplied justification recorded in the audit log. Encouraged but not required — an empty reason still produces an audit row.

string

<= 500 characters

Responses

200

One-shot password generated.

object

temporary_password

required

Plaintext one-shot password — returned ONCE so the admin can share it with the user. The server stores only the hash; this value is never reachable again from any API. Generators must use a cryptographically strong RNG; this response should be considered as sensitive as the hash-bearing original.

string

generated_at

required

string format: date-time

401

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"
}

403

Authenticated but missing required capabilities

object

error

required

Human-readable error summary

string

Example

the request could not be completed

404

Resource not found

object

error

required

Human-readable error summary

string

Example

the request could not be completed

500

Unexpected server error

object

error

required

Human-readable error summary

string

Example

the request could not be completed