Reset a password

Two calls: ask for a link, then use it. Both take a publishable key.

This is also how somebody sets a password for the first time. Accounts are created with an emailed code and have no password until one is chosen, and this flow works the same either way — it proves the address, then sets what they typed. There is no separate "add a password" call to integrate.

1curl -X POST "$BASE/v1/auth/request-password-reset" \2  -H "authorization: Bearer $PK" \3  -H "content-type: application/json" \4  -d '{"email":"ada@example.com","redirectTo":"https://yourapp.com/new-password"}'

1{ "status": true, "message": "If this email exists in our system, check your email for the reset link" }

An address that does not exist gets the same 200 and the same message, and takes a similar amount of time to answer. A faster "no such account" is an enumeration oracle even when the words are careful.

The mail goes out under your project's name. The link is single-use and expires in an hour.

redirectTo must be an origin you registered. A reset link that could land anywhere is an open redirect with a valid session attached, so an unregistered origin is refused with INVALID_REDIRECT_URL.

Your page reads the token from the query string and posts it with the new password.

1curl -X POST "$BASE/v1/auth/reset-password" \2  -H "authorization: Bearer $PK" \3  -H "content-type: application/json" \4  -d '{"token":"…","newPassword":"a-new-long-password"}'

1{ "status": true }

Every other session that person had is revoked. A reset is what someone does when they think their password is known to a stranger, and leaving that stranger's session alive would make the reset cosmetic.

Users with no password

Someone who only ever signed in with Google or a passkey has no password to reset. Requesting one still answers 200 — saying otherwise would disclose how they sign in — but no mail arrives, because there is nothing to reset.

Sending them through request-password-reset is, however, how you give them one: the flow sets a password on an account that had none.

Errors