Password Management

These mutations cover the password lifecycle outside the logged-in session: the forgotten-password email, the variant used for accounts that don’t yet have a password (e.g. customers created through social login), validating reset tokens before showing the reset form, and the reset itself.

All flows are gated by the FIRST_PARTY_AUTH feature and rate limited.

Sending a password reset email

For a customer who has forgotten their password. The mutation always returns successfully even if no account exists for the email, to avoid leaking which addresses are registered. Check error for USER_NOT_FOUND only when you need to differentiate; otherwise treat success as “email sent if account exists”.

mutation ForgottenPassword {
  forgottenPassword(input: { username: "shopper@example.com" }) {
    error
  }
}

Sending a “set password” email

For accounts that exist but have no password yet — typically created via social login or guest checkout. The email wording is different from the forgotten-password version; the resulting token is used in the same resetPassword mutation.

mutation RequestSetPasswordEmail {
  requestSetPasswordEmail(input: { username: "shopper@example.com" }) {
    error
  }
}

Validating a reset token

Before rendering the reset form, check the token from the link. The query reports VALID, INVALID, EXPIRED or ALREADY_USED without consuming the token.

query PasswordResetTokenValidity {
  passwordResetTokenValidity(token: "abc123...")
}

Resetting the password

Consumes the token and logs the customer in on success. The AuthenticationResponse is the same shape as login, so existing client code that handles login responses can be reused.

mutation ResetPassword {
  resetPassword(
    input: {
      token: "abc123..."
      newPassword: "NewSecurePassword1!"
      username: "shopper@example.com"
    }
  ) {
    error
    fieldErrors {
      fieldName
      validators
    }
    customer {
      fullName
    }
  }
}