# Password Password set, reset, and change operations ## Set password for guest users > Sets password for guest users (users with \`user\_type=guest\`, typically\ > created during checkout without registration).\ > \ > \*\*Access Control:\*\*\ > \- Anonymous users: Returns \`redirect\_url\` to home page\ > \- Registered users (already have password): Returns \`redirect\_url\` to password change page\ > \- Guest users: Can set password and become registered users\ > \ > \*\*User Type Transition:\*\*\ > Upon successful password set, user's \`user\_type\` is changed from \`guest\` to \`registered\`.\ > \ > \*\*Password Validation:\*\*\ > Password strength validated according to \`AUTH\_PASSWORD\_VALIDATORS\` setting\ > (Dynamic Configuration).\ > \ > \*\*Response Behavior:\*\*\ > \- Non-AJAX requests: HTTP 302 redirect to \`location\` URL\ > \- AJAX requests (X-Requested-With: XMLHttpRequest): JSON with \`location\` field ```json {"openapi":"3.1.0","info":{"title":"Users API - Authentication, Password, Orders, and Hooks","version":"1.0.0"},"tags":[{"name":"Password","description":"Password set, reset, and change operations"}],"servers":[{"description":"Default commerce site","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce storefront hostname"}}}],"security":[{"SessionCookie":[]}],"components":{"securitySchemes":{"SessionCookie":{"type":"apiKey","in":"cookie","name":"sessionid","description":"Session cookie for authentication"}},"parameters":{"SessionCookieHeader":{"name":"Cookie","in":"header","required":false,"schema":{"type":"string"},"description":"Session cookie in format `sessionid=`.\nMay use site-specific cookie name (e.g., `osessionid`)."},"CSRFTokenHeader":{"name":"X-CSRFToken","in":"header","required":true,"schema":{"type":"string"},"description":"CSRF token for state-changing requests"}},"schemas":{"PasswordSetRequest":{"type":"object","required":["password1","password2"],"properties":{"password1":{"type":"string","format":"password","description":"New password"},"password2":{"type":"string","format":"password","description":"Confirm new password (must match password1).\nValidated against `AUTH_PASSWORD_VALIDATORS` setting."}}}}},"paths":{"/users/password/set/":{"post":{"tags":["Password"],"operationId":"setPassword","summary":"Set password for guest users","description":"Sets password for guest users (users with `user_type=guest`, typically\ncreated during checkout without registration).\n\n**Access Control:**\n- Anonymous users: Returns `redirect_url` to home page\n- Registered users (already have password): Returns `redirect_url` to password change page\n- Guest users: Can set password and become registered users\n\n**User Type Transition:**\nUpon successful password set, user's `user_type` is changed from `guest` to `registered`.\n\n**Password Validation:**\nPassword strength validated according to `AUTH_PASSWORD_VALIDATORS` setting\n(Dynamic Configuration).\n\n**Response Behavior:**\n- Non-AJAX requests: HTTP 302 redirect to `location` URL\n- AJAX requests (X-Requested-With: XMLHttpRequest): JSON with `location` field","parameters":[{"$ref":"#/components/parameters/SessionCookieHeader"},{"$ref":"#/components/parameters/CSRFTokenHeader"},{"name":"X-Requested-With","in":"header","required":false,"schema":{"type":"string","enum":["XMLHttpRequest"]},"description":"Set to 'XMLHttpRequest' for AJAX requests to receive JSON response"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordSetRequest"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/PasswordSetRequest"}}}},"responses":{"200":{"description":"Password set successfully (AJAX request).\nReturns location URL for redirect.","content":{"application/json":{"schema":{"type":"object","properties":{"location":{"type":"string","description":"URL to redirect (typically same endpoint)"}}}}}},"302":{"description":"Password set successfully (non-AJAX request), redirects to location"},"400":{"description":"Validation errors (AJAX request):\n- Password mismatch (password1 != password2)\n- Weak password (fails AUTH_PASSWORD_VALIDATORS)","content":{"application/json":{"schema":{"type":"object","properties":{"form_errors":{"type":"object","description":"Field-level validation errors","additionalProperties":{"type":"array","items":{"type":"string"}}}}}}}}}}}}} ``` ## Set password with SMS OTP verification (guest users) > Sets password for authenticated guest users with phone number verification\ > via SMS OTP. This is a two-step process that transitions guest users to\ > registered users.\ > \ > \*\*Step 1 - Request OTP:\*\*\ > Send \`phone\`, \`password1\`, \`password2\` without \`code\`.\ > System validates fields, sends SMS verification code, and stores\ > confirmation data in session. Returns 202 status.\ > \ > \*\*Step 2 - Verify and Set Password:\*\*\ > Send all fields including \`code\`. System verifies the code against\ > session confirmation data. If valid:\ > \- Password is set and validated against \`AUTH\_PASSWORD\_VALIDATORS\`\ > \- User type changes from \`guest\` to \`registered\`\ > \- Phone number is saved to user profile\ > \- \`verified\_phone\` attribute is set to \`true\`\ > \- Old password is saved to user profile history\ > Returns 200 with success message.\ > \ > \*\*Resend OTP:\*\*\ > Use \`resend: true\` to request a new code. Subject to SMS resend interval\ > restrictions (configured via \`SMS\_OTP\_RESENT\_TIME\_GAP\` system setting).\ > Returns 202 status.\ > \ > \*\*Phone Validation:\*\*\ > Phone must be unique among active users (uses \`UNIQUE\_VALIDATOR\_PHONE\_MESSAGE\`\ > dynamic setting for error message).\ > \ > \*\*Password Validation:\*\*\ > Password strength validated according to \`AUTH\_PASSWORD\_VALIDATORS\` setting\ > (Dynamic Configuration).\ > \ > Throttling scope: \`register\`. ```json {"openapi":"3.1.0","info":{"title":"Users API - Authentication, Password, Orders, and Hooks","version":"1.0.0"},"tags":[{"name":"Password","description":"Password set, reset, and change operations"}],"servers":[{"description":"Default commerce site","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce storefront hostname"}}}],"security":[{"SessionCookie":[]}],"components":{"securitySchemes":{"SessionCookie":{"type":"apiKey","in":"cookie","name":"sessionid","description":"Session cookie for authentication"}},"parameters":{"SessionCookieHeader":{"name":"Cookie","in":"header","required":false,"schema":{"type":"string"},"description":"Session cookie in format `sessionid=`.\nMay use site-specific cookie name (e.g., `osessionid`)."},"CSRFTokenHeader":{"name":"X-CSRFToken","in":"header","required":true,"schema":{"type":"string"},"description":"CSRF token for state-changing requests"}},"schemas":{"PasswordSetSmsOtpRequest":{"type":"object","required":["password1","password2","phone"],"properties":{"password1":{"type":"string","format":"password","description":"New password"},"password2":{"type":"string","format":"password","description":"Confirm new password (must match password1)"},"phone":{"type":"string","maxLength":60,"description":"Phone number for SMS verification"},"code":{"type":"string","description":"SMS verification code. Omit on first request\nto receive OTP."},"resend":{"type":"boolean","default":false,"description":"Set to true to request a new verification code"}}}}},"paths":{"/users/password-sms-otp/set/":{"post":{"tags":["Password"],"operationId":"setPasswordWithSmsOtp","summary":"Set password with SMS OTP verification (guest users)","description":"Sets password for authenticated guest users with phone number verification\nvia SMS OTP. This is a two-step process that transitions guest users to\nregistered users.\n\n**Step 1 - Request OTP:**\nSend `phone`, `password1`, `password2` without `code`.\nSystem validates fields, sends SMS verification code, and stores\nconfirmation data in session. Returns 202 status.\n\n**Step 2 - Verify and Set Password:**\nSend all fields including `code`. System verifies the code against\nsession confirmation data. If valid:\n- Password is set and validated against `AUTH_PASSWORD_VALIDATORS`\n- User type changes from `guest` to `registered`\n- Phone number is saved to user profile\n- `verified_phone` attribute is set to `true`\n- Old password is saved to user profile history\nReturns 200 with success message.\n\n**Resend OTP:**\nUse `resend: true` to request a new code. Subject to SMS resend interval\nrestrictions (configured via `SMS_OTP_RESENT_TIME_GAP` system setting).\nReturns 202 status.\n\n**Phone Validation:**\nPhone must be unique among active users (uses `UNIQUE_VALIDATOR_PHONE_MESSAGE`\ndynamic setting for error message).\n\n**Password Validation:**\nPassword strength validated according to `AUTH_PASSWORD_VALIDATORS` setting\n(Dynamic Configuration).\n\nThrottling scope: `register`.","parameters":[{"$ref":"#/components/parameters/SessionCookieHeader"},{"$ref":"#/components/parameters/CSRFTokenHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordSetSmsOtpRequest"}}}},"responses":{"200":{"description":"Password set successfully (Step 2 completed)","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","description":"Success message"}}}}}},"202":{"description":"SMS verification code sent (Step 1 or resend).\nConfirmation data stored in session.","content":{"application/json":{"schema":{"type":"object","description":"Returns submitted data (without code) or empty response."}}}},"400":{"description":"Validation errors:\n- Password mismatch (password1 != password2)\n- Weak password (fails AUTH_PASSWORD_VALIDATORS)\n- Phone already exists for another active user\n- Phone format invalid\n- Incorrect OTP code during verification"},"401":{"description":"Authentication required (must be logged in)"},"429":{"description":"Too many requests:\n- Throttling limit exceeded (register scope)\n- SMS resend interval not elapsed"}}}}}} ``` ## Request password reset via email > Initiates password reset flow by sending a reset link via email.\ > \ > \*\*User Filtering:\*\*\ > Only sends email to users who:\ > \- Are registered users (not guest users)\ > \- Have verified email addresses\ > \- Are active users\ > \ > \*\*Email Content:\*\*\ > Email is rendered using template from \`RESET\_EMAIL\_HTML\_TEMPLATE\` setting\ > (Dynamic Configuration). The email contains:\ > \- Password reset link with unique token\ > \- Frontend ID in extra context (from \`X-Frontend-ID\` header if valid)\ > \ > \*\*Security:\*\*\ > Always returns success (200) to prevent email enumeration, regardless of\ > whether the email exists in the system.\ > \ > \*\*User Translation:\*\*\ > Email is sent in user's preferred language (\`user.language\_code\`).\ > \ > Throttling scope: \`password-reset\`. ```json {"openapi":"3.1.0","info":{"title":"Users API - Authentication, Password, Orders, and Hooks","version":"1.0.0"},"tags":[{"name":"Password","description":"Password set, reset, and change operations"}],"servers":[{"description":"Default commerce site","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce storefront hostname"}}}],"paths":{"/users/password/reset/":{"post":{"tags":["Password"],"operationId":"resetPasswordEmail","summary":"Request password reset via email","description":"Initiates password reset flow by sending a reset link via email.\n\n**User Filtering:**\nOnly sends email to users who:\n- Are registered users (not guest users)\n- Have verified email addresses\n- Are active users\n\n**Email Content:**\nEmail is rendered using template from `RESET_EMAIL_HTML_TEMPLATE` setting\n(Dynamic Configuration). The email contains:\n- Password reset link with unique token\n- Frontend ID in extra context (from `X-Frontend-ID` header if valid)\n\n**Security:**\nAlways returns success (200) to prevent email enumeration, regardless of\nwhether the email exists in the system.\n\n**User Translation:**\nEmail is sent in user's preferred language (`user.language_code`).\n\nThrottling scope: `password-reset`.","parameters":[{"name":"X-Frontend-ID","in":"header","required":false,"schema":{"type":"string"},"description":"Frontend identifier for multi-frontend setups.\nMust be in `VALID_FRONTEND_IDS` setting (Dynamic Configuration).\nPassed to email template context as `frontend_id`."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordResetEmailRequest"}}}},"responses":{"200":{"description":"Reset email sent if address exists.\nResponse is identical for existing and non-existing emails\nto prevent enumeration.","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"Confirmation message"}}}}}},"429":{"description":"Too many reset requests"}}}}},"components":{"schemas":{"PasswordResetEmailRequest":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email","description":"Email address for password reset link"}}}}}} ``` ## Request password reset via SMS > Initiates password reset flow by sending a reset SMS with a password\ > reset link to the provided phone number.\ > \ > \*\*User Lookup:\*\*\ > Searches for active users by phone number. Only sends SMS if:\ > \- Phone number exists in the system\ > \- User is active\ > \ > \*\*SMS Content:\*\*\ > SMS contains:\ > \- Site name\ > \- Password reset URL with token (format: \`/password-reset/{uid}/{token}/\`)\ > \- User information\ > \ > \*\*Token Generation:\*\*\ > A secure, time-limited token is generated for password reset confirmation.\ > \ > \*\*Security:\*\*\ > Always returns success message (200) to prevent phone number enumeration,\ > regardless of whether the phone exists in the system.\ > \ > Throttling scope: \`password-reset\`. ```json {"openapi":"3.1.0","info":{"title":"Users API - Authentication, Password, Orders, and Hooks","version":"1.0.0"},"tags":[{"name":"Password","description":"Password set, reset, and change operations"}],"servers":[{"description":"Default commerce site","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce storefront hostname"}}}],"paths":{"/users/password/reset-with-phone/":{"post":{"tags":["Password"],"operationId":"resetPasswordPhone","summary":"Request password reset via SMS","description":"Initiates password reset flow by sending a reset SMS with a password\nreset link to the provided phone number.\n\n**User Lookup:**\nSearches for active users by phone number. Only sends SMS if:\n- Phone number exists in the system\n- User is active\n\n**SMS Content:**\nSMS contains:\n- Site name\n- Password reset URL with token (format: `/password-reset/{uid}/{token}/`)\n- User information\n\n**Token Generation:**\nA secure, time-limited token is generated for password reset confirmation.\n\n**Security:**\nAlways returns success message (200) to prevent phone number enumeration,\nregardless of whether the phone exists in the system.\n\nThrottling scope: `password-reset`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordResetPhoneRequest"}}}},"responses":{"200":{"description":"Success response (always returned regardless of phone existence).\nSMS is sent only if phone belongs to an active user.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"string","description":"Confirmation message (translated)"}}}}}},"400":{"description":"Validation errors:\n- Phone format is invalid"},"429":{"description":"Throttling limit exceeded (password-reset scope)"}}}}},"components":{"schemas":{"PasswordResetPhoneRequest":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","maxLength":60,"description":"Phone number for password reset SMS"}}}}}} ``` ## Change password for authenticated user > Changes password for the currently authenticated user.\ > Requires verification of the old password and two matching new password entries.\ > \ > \*\*Password Validation:\*\*\ > New password is validated against \`AUTH\_PASSWORD\_VALIDATORS\` setting\ > (Dynamic Configuration).\ > \ > \*\*Side Effects:\*\*\ > \- Old password is saved to user profile history\ > \- User type is updated to \`registered\` if not already\ > \- Notification email is sent asynchronously\ > \ > \*\*Email Notification:\*\*\ > A confirmation email is sent to the user with subject "Password Changed".\ > CC/BCC recipients can be configured via \`EMAIL\_BCC\_AND\_CC\` setting.\ > \ > \*\*Audit Logging:\*\*\ > Password change events are logged for security audit purposes.\ > Password values are not stored in audit logs.\ > \ > \*\*Error Handling:\*\*\ > Invalid old password returns "Invalid password." error message. ```json {"openapi":"3.1.0","info":{"title":"Users API - Authentication, Password, Orders, and Hooks","version":"1.0.0"},"tags":[{"name":"Password","description":"Password set, reset, and change operations"}],"servers":[{"description":"Default commerce site","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce storefront hostname"}}}],"security":[{"SessionCookie":[]}],"components":{"securitySchemes":{"SessionCookie":{"type":"apiKey","in":"cookie","name":"sessionid","description":"Session cookie for authentication"}},"parameters":{"SessionCookieHeader":{"name":"Cookie","in":"header","required":false,"schema":{"type":"string"},"description":"Session cookie in format `sessionid=`.\nMay use site-specific cookie name (e.g., `osessionid`)."},"CSRFTokenHeader":{"name":"X-CSRFToken","in":"header","required":true,"schema":{"type":"string"},"description":"CSRF token for state-changing requests"}},"schemas":{"PasswordChangeRequest":{"type":"object","required":["old_password","new_password1","new_password2"],"properties":{"old_password":{"type":"string","format":"password","description":"Current password"},"new_password1":{"type":"string","format":"password","description":"New password"},"new_password2":{"type":"string","format":"password","description":"Confirm new password (must match new_password1)"}}}}},"paths":{"/users/password/change/":{"post":{"tags":["Password"],"operationId":"changePassword","summary":"Change password for authenticated user","description":"Changes password for the currently authenticated user.\nRequires verification of the old password and two matching new password entries.\n\n**Password Validation:**\nNew password is validated against `AUTH_PASSWORD_VALIDATORS` setting\n(Dynamic Configuration).\n\n**Side Effects:**\n- Old password is saved to user profile history\n- User type is updated to `registered` if not already\n- Notification email is sent asynchronously\n\n**Email Notification:**\nA confirmation email is sent to the user with subject \"Password Changed\".\nCC/BCC recipients can be configured via `EMAIL_BCC_AND_CC` setting.\n\n**Audit Logging:**\nPassword change events are logged for security audit purposes.\nPassword values are not stored in audit logs.\n\n**Error Handling:**\nInvalid old password returns \"Invalid password.\" error message.","parameters":[{"$ref":"#/components/parameters/SessionCookieHeader"},{"$ref":"#/components/parameters/CSRFTokenHeader"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordChangeRequest"}}}},"responses":{"200":{"description":"Password changed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string","description":"Success confirmation message (translated)"}}}}}},"400":{"description":"Validation errors:\n- Invalid old password (\"Invalid password.\")\n- Password mismatch (new_password1 != new_password2)\n- Weak password (fails AUTH_PASSWORD_VALIDATORS)","content":{"application/json":{"schema":{"type":"object","properties":{"old_password":{"type":"array","items":{"type":"string"}},"new_password2":{"type":"array","items":{"type":"string"}}}}}}},"401":{"description":"Authentication required"}}}}}} ``` ## Reset password via SMS verification code > Initiates and completes a password reset flow using SMS verification.\ > This is a two-step process.\ > \ > \*\*Step 1 — Request verification code:\*\*\ > Send \`phone\` without \`code\`. If the phone number belongs to a registered\ > account, a one-time code is sent via SMS. Returns 202 regardless of\ > whether the phone number exists, to prevent enumeration.\ > \ > \*\*Step 2 — Verify code and redirect:\*\*\ > Send \`phone\` with \`code\`. If the code is valid:\ > \- API/AJAX requests: Returns a \`redirect\` URL to the password reset\ > confirmation page.\ > \- Browser requests: Redirects (302) to the password reset confirmation\ > page where the new password can be set.\ > \ > \*\*Resend code:\*\*\ > Send \`resend: true\` with \`phone\` to request a new code. Subject to\ > resend interval restrictions (see \`SMS\_OTP\_RESENT\_TIME\_GAP\` in\ > System Configuration).\ > \ > \*\*Security:\*\*\ > Only registered accounts (not guest accounts) can reset their password\ > via SMS. The response is identical for existing and non-existing phone\ > numbers to prevent enumeration.\ > \ > Throttling scope: \`password-reset\`. ```json {"openapi":"3.1.0","info":{"title":"Users API - Authentication, Password, Orders, and Hooks","version":"1.0.0"},"tags":[{"name":"Password","description":"Password set, reset, and change operations"}],"servers":[{"description":"Default commerce site","url":"https://{commerce_url}","variables":{"commerce_url":{"default":"sandbox.akinon.com","description":"Commerce storefront hostname"}}}],"paths":{"/users/password/reset-with-sms-otp/":{"post":{"tags":["Password"],"operationId":"resetPasswordWithSmsOtp","summary":"Reset password via SMS verification code","description":"Initiates and completes a password reset flow using SMS verification.\nThis is a two-step process.\n\n**Step 1 — Request verification code:**\nSend `phone` without `code`. If the phone number belongs to a registered\naccount, a one-time code is sent via SMS. Returns 202 regardless of\nwhether the phone number exists, to prevent enumeration.\n\n**Step 2 — Verify code and redirect:**\nSend `phone` with `code`. If the code is valid:\n- API/AJAX requests: Returns a `redirect` URL to the password reset\n confirmation page.\n- Browser requests: Redirects (302) to the password reset confirmation\n page where the new password can be set.\n\n**Resend code:**\nSend `resend: true` with `phone` to request a new code. Subject to\nresend interval restrictions (see `SMS_OTP_RESENT_TIME_GAP` in\nSystem Configuration).\n\n**Security:**\nOnly registered accounts (not guest accounts) can reset their password\nvia SMS. The response is identical for existing and non-existing phone\nnumbers to prevent enumeration.\n\nThrottling scope: `password-reset`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PasswordResetSmsOtpRequest"}}}},"responses":{"200":{"description":"OTP verified successfully (AJAX/API request).\nReturns redirect URL to the password reset confirmation page.","content":{"application/json":{"schema":{"type":"object","properties":{"redirect":{"type":"string","description":"Relative URL to the password reset confirmation page."}}}}}},"202":{"description":"Verification code sent or resent successfully.\nAlso returned when the phone number is not found (identical response\nto prevent enumeration)."},"302":{"description":"OTP verified successfully (browser request).\nRedirects to the password reset confirmation page."},"400":{"description":"Phone number format is invalid."},"406":{"description":"OTP verification failed. The response includes a machine-readable\n`error_code` and a human-readable `non_field_errors` message.\n\nError codes:\n- `sms_verification_100_1`: Phone number does not match the session record\n- `sms_verification_100_2`: Verification code is incorrect\n- `sms_verification_100_3`: SMS resend interval has not elapsed yet\n- `sms_verification_100_4`: Verification code has expired","content":{"application/json":{"schema":{"type":"object","properties":{"non_field_errors":{"type":"string","description":"Human-readable error message."},"error_code":{"type":"string","description":"Machine-readable error code."}}}}}},"429":{"description":"Throttling limit exceeded (password-reset scope).","content":{"application/json":{"schema":{"type":"object","properties":{"detail":{"type":"string"}}}}}}}}}},"components":{"schemas":{"PasswordResetSmsOtpRequest":{"type":"object","required":["phone"],"properties":{"phone":{"type":"string","maxLength":60,"description":"Phone number associated with the account.\nMust pass phone number format validation."},"code":{"type":"string","description":"Verification code received via SMS in Step 1.\nOmit on first request to trigger SMS delivery.\nInclude on second request to verify the code."},"resend":{"type":"boolean","default":false,"description":"Set to true to request a new verification code."}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://apidocs.akinon.com/commerce-openapis/users/module-3/password.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.