Forgot password

Huudis owns passwords, so it owns password reset too. Your app should never collect a "new password" form itself — link to Huudis's reset flow.

The flow at a glance

User clicks Forgot your password? on the sign-in screen (or hits /forgot-password directly).
User enters their email.
Huudis sends a one-time reset link to that email — regardless of whether the email is registered. We never disclose account existence.
User clicks the link, which lands them on /reset-password?token=….
User enters and confirms a new password.
Huudis hashes the new password, invalidates all existing sessions for the user, and signs the user in with a fresh session.

Step 1 — Request reset

POST /api/v1/auth/forgot-password
Content-Type: application/json

{
  "email": "alice@example.com"
}

Always returns 200 OK with { "data": { "sent": true } }, even if the email doesn't exist. This is intentional — disclosing which emails are registered is an enumeration leak.

Rate limit: 5 requests per hour per email + per IP. After that, requests are quietly dropped (still 200 OK, no email sent).

Step 2 — Reset email

The email contains a link of the form:

https://huudis.com/reset-password?token=prt_xxxxxxxxxxxxxxxxxxxxxxxx

The token is single-use and expires in 60 minutes. Clicking it after expiry shows a "this link has expired" screen with a button to request a new one.

Step 3 — Set new password

POST /api/v1/auth/reset-password
Content-Type: application/json

{
  "token": "prt_xxx",
  "newPassword": "the-new-password"
}

Huudis validates the password against the same policy as sign-up:

Minimum 10 characters.
Not present in the leaked-password dictionary (HIBP top 100k).

On success, every existing session for this user is revoked, all refresh tokens are killed, and a fresh session cookie is set.

All existing sessions are revoked on password change. This is a deliberate security boundary — a user changing their password almost always means "I think someone might have access I don't want them to have", and we treat it that way. Apps signed in via OIDC will see refresh-token failures and bounce the user back through sign-in.

Triggering reset from an admin

A workspace admin can trigger a reset email for any end user from the dashboard:

Dashboard → End users → [user] → Send password reset

Or via the API:

POST /api/v1/ops/end-users/:id/send-password-reset

This is audit-logged with the operator's identity. Use it sparingly — for support flows where the user has lost access to their email entirely, Huudis support can verify identity out-of-band and trigger a reset directly.

Sign in — the standard sign-in flow.
Social providers — users who signed up via Google never have a Huudis password to reset.