Skip to content
/api/v1/auth/forgetpassword

Initiate the password-reset flow.

Initiate the password-reset flow. Sends a one-time reset link to the registered email. EXEMPT (`cost: 0`). Token expires after 24 hours. Always returns 200 with a generic message regardless of whether the email is registered (anti-enumeration).

freeSince v1.0.0

Why use this

Send a password-reset email containing a one-time JWT token. EXEMPT (`cost: 0`). Tokens expire after 24 hours; if a previous unexpired token already exists for the user, the existing token is re-used (no duplicate email). The link in the email points at GET /api/v1/auth/verifyPasswordLink which 302-redirects to the FinRadar frontend's `/reset-password?token=…` page; the frontend then PUTs `{token, newpassword}` to /api/v1/auth/newpassword to finalize. The redirect target is server-controlled — there is no caller-supplied redirect-URL parameter (the previous `weblink` field was removed in the 2026-05-18 security hardening because it enabled an open-redirect that could exfiltrate the user UUID).

Common use case

Frontend 'Forgot password?' form: user enters email → POST here → generic 'check your email' toast (always 200, never 400) → user checks email → clicks link → 302 to frontend `/reset-password?token=…` page → user enters new password → frontend PUTs to /api/v1/auth/newpassword to finalize.

Password-reset email dispatch. EXEMPT (cost: 0). The endpoint generates a one-time JWT token tied to the user's email and stores it in the email_verifies table with a 24-hour TTL. If a still-valid token already exists, the existing token is silently re-used (no duplicate email is sent). The reset link in the email points at GET /api/v1/auth/verifyPasswordLink — that handler 302-redirects to the FinRadar frontend's /reset-password?token=<token> page (the redirect target is hard-coded; no caller-supplied URL is honoured). The frontend then collects the new password and PUTs {token, newpassword} to /api/v1/auth/newpassword. The token row is consumed atomically with the password update, so accidentally pre-fetching the email link does not burn the user's reset token. Distinct from the verification email flow at /auth/verifyEmail (account-activation path, separate email_verifies row semantics — but note both flows currently share the same table). To register a new account use POST /api/v1/auth/register; to log in once the password is reset use POST /api/v1/auth/login.

Parameters

NameInRequiredDefaultAllowedDescriptionExample
emailbodyrequired——Email address. Lowercased server-side. The endpoint ALWAYS returns 200 with a generic message regardless of whether the email is registered — this is intentional and prevents account enumeration. Only a registered user actually receives an email.user@example.com

Response schema

FieldTypeNullableDescription
messagestringnoGeneric status message. Always identical across the registered / unregistered / already-sent / SMTP-failed cases to prevent enumeration. UI should show a 'check your email' toast on every 200.

Sample response

·
  • "message": "If that email is registered, a password-reset link has been sent."
}

Errors

StatusLabelDescription
200OKRequest succeeded.
400Bad RequestInvalid query, body, or path parameter.
401UnauthorizedMissing or invalid Authorization header / api_Token.
402Payment RequiredInsufficient token balance for this call. Top up
429Too Many RequestsRate limit exceeded for your tier (see /pricing for tier limits). Tier limits
500Server ErrorUnexpected server-side failure. Retry with backoff; report if persistent.

Code samples

curl -X POST "https://api.finradar.ai/api/v1/auth/forgetpassword" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Generate an API key in /account/credentials to run live queries (literal YOUR_API_KEY placeholder shown until then).