Send a password reset request
Send a password-reset email to a user.
Trigger GoTrue's POST /recover endpoint to email the user a one-time recovery link. The link drops them back at your application with a session that has PASSWORD_RECOVERY semantics — your app should then call update_user with the new password.
Does not require an active session: this is the entry point for the "forgot password" flow.
Signature
supabase.auth.reset_password_for_email(email, options = {})Two positional arguments: an email String, and an optional options Hash.
A keyword-style alias reset_password_email(email:, **options) is also provided — same behaviour, different calling style. See the callout below.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
email | String | Required | The email address to send the recovery link to. Positional, not nested under options. |
options | Hash | Optional | Nested options: redirect_to (String, URL embedded in the recovery email; the user lands here after clicking the link), captcha_token (String, response from a hCaptcha/Turnstile challenge if your project enforces one). |
Returns
GoTrue currently returns an empty JSON object on success, so the parsed body is a Hash. Treat this as a fire-and-forget call — branch on whether an exception was raised, not on the return value. On failure (rate limit, invalid email, captcha required) Supabase::Auth::Errors::AuthApiError is raised.
Example — minimal
supabase.auth.reset_password_for_email("ada@example.com")Example — with redirect and captcha
supabase.auth.reset_password_for_email(
"ada@example.com",
redirect_to: "https://app.example.com/auth/reset-callback",
captcha_token: "10000000-aaaa-bbbb-cccc-000000000001"
)Example — completing the flow
# Step 1: send the email
supabase.auth.reset_password_for_email(
"ada@example.com",
redirect_to: "https://app.example.com/auth/reset-callback"
)
# Step 2: after the user clicks the link and your callback page restores the session,
# update the password on the recovered session.
supabase.auth.update_user(password: "new-strong-password-2026")Two calling styles
Two calling styles exist:
reset_password_for_email(email, options)— positional form.reset_password_email(email:, **options)— keyword form. Useful when you want to splat an existing hash without naming theoptions:key.
Both forward to the same GoTrue endpoint.