Reset a password using a reset token

POST 
/auth/reset-password

Consumes the reset token from the forgot-password email and sets a new password. Enforces the account's password policy. Emits auth.password.reset. Public endpoint, throttled to 5/min/IP.

Request

Responses

201

Resource created. Body follows the shared { data, meta } envelope; data is the newly-created resource.

204

Password updated.

400

Token invalid/expired or new password fails policy.

409

The request conflicts with the current state of the target resource — a duplicate unique field on registration, an idempotency-key replay with a different payload, or a webhook eventId that has already been processed. error.code may be CONFLICT or IDEMPOTENCY_CONFLICT depending on the cause.

429

Rate limit exceeded. Global default is 120 requests/minute per IP; auth-flow, OTP, self-registration, WebAuthn, IRA lookup, and public-lead endpoints carry tighter per-endpoint limits. Retry after the delay indicated by the Retry-After header.

Response Headers

Retry-After

Seconds to wait before retrying.

500

Unhandled server error. The response carries a meta.requestId correlator you can hand to platform operations to trace the failure through structured logs and the hash-chained audit trail. Retry with the same Idempotency-Key header if the endpoint accepts idempotency.