borkoldocs

Customers

Password reset

Request a password reset email and complete the reset with the emailed token.

View as Markdown

Password reset is a two-step flow: forgot-password emails the customer a reset link, reset-password consumes the token from that link. Both require the customers:write scope and neither requires X-Customer-Token. Both carry the extra credential-endpoint rate limit of 10 requests per minute per IP.

Reset tokens are single-use, stored hashed (SHA-256), and expire 60 minutes after they are issued. The reset link points at your store's configured storefront URL in the format {storefront_url}/account/reset?token=...&email=...; your storefront page at that path should read both query parameters and submit them to reset-password. If the store has no storefront_url configured, no email is sent (the endpoint still returns 202).

POST /v1/api/customers/forgot-password

Request a password reset email. Always returns 202 with the same body whether or not an account with that email exists, so the endpoint cannot be used to enumerate accounts.

Body parameters

NameTypeRequiredDescription
emailstringYesValid email address. Lowercased server-side before lookup.
Request
curl -X POST https://api.borkol.com/v1/api/customers/forgot-password \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com"}'

Status: 202 Accepted.

Response
{
  "message": "If the account exists, a reset link has been sent."
}

Errors

  • 422 when email is missing or not a valid email address.
  • 429 when the 10 requests per minute per IP limit is exceeded.

POST /v1/api/customers/reset-password

Complete a password reset with the token from the emailed link. On success this sets the new password, marks the account non-guest, sets email_verified_at if it was unset, and revokes all of the customer's session tokens (every device is logged out). An invalid or expired token leaves the account untouched.

Body parameters

NameTypeRequiredDescription
emailstringYesValid email address. Must match the account the token was issued for.
tokenstringYesThe plain token from the reset link's token query parameter.
passwordstringYesThe new password. Minimum 8 characters.
Request
curl -X POST https://api.borkol.com/v1/api/customers/reset-password \
  -H "Authorization: Bearer {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"email":"jane@example.com","token":"kJ8s...64-char-token...Qw2","password":"new-s3cret-pass"}'

Status: 200 OK.

Response
{
  "message": "Password updated."
}

Errors

  • 422 with errors.token ["This reset link is invalid or expired."] for an unknown email, a wrong token, an already-used token, or a token older than 60 minutes.
  • 422 for field validation failures (missing fields, password shorter than 8 characters).
  • 429 when the 10 requests per minute per IP limit is exceeded.