POST/auth/request-password-reset

Request a password reset

Starts a password reset by emailing a one-time code to the address given, and always reports success so the call cannot be used to discover which addresses are registered.

AccessNo sign-in required

This is the first step of the two-step reset. The platform emails a reset code to the address, and the holder then sets a new password with POST /auth/reset-password, which needs the same address and that code. Nothing about the account changes until the second call succeeds, so the current password keeps working in the meantime.

Success does not confirm the address exists

The response always reports success, whether or not the address belongs to an account. That is deliberate: it stops the endpoint being used to discover which addresses are registered. Show the caller a neutral "check your email" message rather than telling them the address was not found, and do not treat Success as proof that an email was sent.

Body parameters

emailstringrequired

The address to send the reset code to.

locationstringoptional

Where the request is being made from, if your client can determine it.

devicestringoptional

The device the request is being made from, if your client can determine it.

bash

curl -X POST "$SQRL_API/auth/request-password-reset" \
  -H "content-type: application/json" \
  -d '{
        "email": "operator@example.com",
        "location": "London, GB",
        "device": "treasury-ops-cli"
      }'

const res = await fetch(`${process.env.SQRL_API}/auth/request-password-reset`, {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    email: "operator@example.com",
    location: "London, GB",
    device: "treasury-ops-cli",
  }),
});
const { Success } = await res.json();

rust

let res = client
    .post(format!("{}/auth/request-password-reset", api_base))
    .json(&serde_json::json!({
        "email": "operator@example.com",
        "location": "London, GB",
        "device": "treasury-ops-cli",
    }))
    .send()
    .await?;

Response200 OK

{
"Success": true
}

#What happens next

If the address belongs to an account, a reset code arrives by email. Collect that code and the new password from the holder and send both to POST /auth/reset-password. This code is separate from the two-factor code used by POST /auth/otp-validate: each one only works on the call it was issued for.

Was this page helpful?