Password & OTP Operations

`POST` Set New Password

This endpoint enables authenticated users to set a password for the first time if they are new users or if their account currently lacks a usable password.

Path: /users/password/set/

Authentication Required: Yes

Headers:

Content-Type: application/json
Accept-Language: <iso_language_code>
x-csrftoken: <token>
Cookie: <cookie-name>=<session_id>

Body Parameters

Property	Data Type	Required	Description
new_password1	String	True	The new password the user wants to set, which must comply with the password validation rules.
new_password2	String	True	Confirmation of the new password, which must match `new_password1`.

Request Body

{
    "new_password1": "MyNewSecurePassword123!",
    "new_password2": "MyNewSecurePassword123!"
}

Example Request

import requests
import json

url = "https://{commerce_url}/users/password/set/"

headers = {
    'Content-Type': 'application/json',
    'X-CSRFToken': '<token>',
    'Cookie': '<cookie-name>=<session_id>'
}

payload = json.dumps({
    "new_password1": "MyNewSecurePassword123!",
    "new_password2": "MyNewSecurePassword123!"
})

response = requests.post(url, headers=headers, data=payload)
print(response.text)

Example Response (200 OK)

{
    "success": "Your password has been set successfully."
}

Example Response (302 Redirect)

If the user already has a usable password, they are redirected to the change password page to update their existing password:

{
    "redirect_url": "/account/change-password/"
}

If the user is anonymous, they are redirected to the specified home page:

{
    "redirect_url": "/home/"
}

Example Response (400 Bad Request)

{
    "new_password2": ["The two password fields didn’t match."]
}

`POST` Change Password

This endpoint is used to change the user's password. Once the password change is successful, a confirmation email will be sent to the user’s registered email address. The user must be authenticated to access this endpoint.

Path: /users/password/change/

Authentication Required: Yes

Headers:

Content-Type: `application/json`
Accept-Language: <iso_language_code>
Cookie: <cookie-name>=<session_id>
x-csrftoken: <token>

Body Parameters

Property	Data Type	Required	Description
old_password	string	True	The user’s current password.
new_password1	string	True	The new password that the user wants to set. It should meet the password policy criteria (e.g., minimum length, special characters, etc.).
new_password2	string	True	A confirmation of the new password. This field must match `new_password1` to ensure the user has entered the correct password.

Request Body

{
    "old_password": "old_pass",
    "new_password1": "new_pass",
    "new_password2": "new_pass"
}

Example Request

import requests
import json

url = "https://{commerce_url}/users/password/change/"

payload = json.dumps({
  "old_password": "oldpass",
  "new_password1": "newpass",
  "new_password2": "newpass"
})

headers = {
  'Content-Type': 'application/json',
  'Accept-Language: '<iso_language_code>',
  'Cookie': '<cookie-name>=<session_id>',
  'x-csrftoken': '<token>'
}

response = requests.post(url, headers=headers, data=payload)

print(response.text)

Example Response (200 OK)

If the request is successfully processed and the password is updated, the response will contain a success message confirming that the password has been changed.

{
    "success": "New password has been saved."
}

Example Response (400 Bad Request)

When the old_password provided is incorrect:

{
    "old_password": [
        "Invalid password."
    ]
}

When the new_password1 and new_password2 fields do not match:

{
    "new_password2": [
        "The two password fields didn't match."
    ]
}

`POST` Initiate Password Reset

This endpoint is used to initiate a password reset process by sending a password reset email to the user. If the email provided in the request body is registered in the system, the user will receive an email with instructions on how to reset their password.

Path: /users/password/reset/

Authentication Required: No

Headers:

Content-Type: application/json
Accept-Language: <iso_language_code>
x-csrftoken: <token>

Body Parameters

Property	Data Type	Required	Description
email	string	True	The email address associated with the user account for which the password reset is being requested.

Request Body

{
    "email": "<USER_EMAIL>"
}

Example Request

import requests
import json

url = "https://{commerce_url}/users/password/reset/"

payload = json.dumps({
  "email": "<USER_EMAIL>"
})

headers = {
  'Content-Type': 'application/json',
  'Accept-Language: '<iso_language_code>',
  'x-csrftoken': '<token>'
}

response = requests.post(url, headers=headers, data=payload)

print(response.text)

Example Response (200 OK)

If the email address provided is valid and associated with an account, the response body will contain a success message.

{
    "success": "Password reset e-mail has been sent.
}

Example Response (400 Bad Request)

When the provided email address is invalid or not formatted correctly:

{
    "email": [
        "Enter a valid email address."
    ]
}

`GET` Validate Password Reset URL

This endpoint verifies if a given password reset URL is valid. The URL is typically generated when a user requests a password reset and is included in an email sent to the user. The validity of the link ensures that the reset process is secure and can only be accessed within a specific timeframe or if the token is unaltered.

The parameters in the path <uidb64> and <token> are generated and sent by the Commerce system.

Path: /users/api-reset/<uidb64>/<token>/

Authentication Required: No

Headers:

Accept-Language: <iso_language_code>

Example Request

import requests

headers = {
  'Accept-Language': '<iso_language_code>'
}

url = "https://{commerce_url}/users/api-reset/<uidb64>/<token>/"

response = requests.get(url)
print(response.json())

Example Response (200 OK)

{
    "validlink": true
}

Response Parameters

Property	Data Type	Description
validlink	Boolean	Indicates whether the password reset URL is valid. A value of `true` means the URL is valid, while `false` indicates the link is expired or invalid.

`POST` Complete Password Reset with JSON Response

This endpoint allows users to reset their password by providing a new password and its confirmation. It uses the unique uidb64 and token parameters from the password reset email to identify the user and ensure the request's validity. This API ensures that both passwords match and comply with the application's password rules before the change is finalized.

Path: /users/api-reset/<uidb64>/<token>/

Authentication Required: No

Headers:

Content-Type: application/json
Accept-Language: <iso_language_code>
x-csrftoken: <token>

Body Parameters

Property	Data Type	Required	Description
new_password1	string	True	The new password that the user wants to set. It must adhere to password policy rules, such as length or complexity.
new_password2	string	True	The confirmation of the new password. Both `new_password1` and `new_password2` must match.

Request Body

{
    "new_password1": "StrongP@ssw0rd",
    "new_password2": "StrongP@ssw0rd"
}

Example Request

import requests

url = "https://{commerce_url}/users/api-reset/<uidb64>/<token>/"

payload = 'new_password1=StrongP%40ssw0rd&new_password2=StrongP%40ssw0rd'
headers = {
  'x-requested-with': 'XMLHttpRequest',
  'Accept-Language': '<iso_language_code>',
  'x-csrftoken': '<token>',
  'Content-Type': 'application/x-www-form-urlencoded'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Example Response (200 OK)

Indicates that the password has been successfully reset.

{}

Example Response (400 Bad Request)

Indicates issues with the input, such as mismatched passwords.

{
  "errors": {
    "new_password2": [
    "İki parola alanı uyuşmadı."
    ]
  },
  "validlink": true
}

`POST` Complete Password Reset with HTML Response

This endpoint allows users to set a new password after receiving a password reset email. The user must provide a new password and confirm it by entering it again.

The parameters in the path <uidb64> and <token> are generated and sent by the Commerce system.

Path: /users/reset/<uidb64>/<token>/

Authentication Required: Yes

Headers:

Content-Type: application/json
Accept-Language: <iso_language_code>
Cookie: <cookie-name>=<session_id>
x-csrftoken: <token>

Body Parameters

Property	Data Type	Required	Description
new_password1	string	True	The new password for the user. It should meet the password policy criteria (e.g., length, complexity).
new_password2	string	True	A confirmation of the new password. It must match new_password1 for the change to be applied.

Request Body

{
   "new_password1": "<NEW_PASSWORD>",
   "new_password2": "<NEW_PASSWORD>"
}

Example Request

import requests
import json

url = "https://{commerce_url}/users/reset/<uidb64>/<token>/"

payload = json.dumps({
  "new_password1": "newpass",
  "new_password2": "newpass"
})

headers = {
  'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)

print(response.text)

Example Response (200 OK)

No content is returned when the request is successful.

`POST` Confirm Password Reset

This endpoint enables users to confirm a password reset by submitting a valid token and UID. Upon successful confirmation, the user's password will be updated.

Path: /users/password/reset/confirm/

Authentication Required: No

Headers:

Content-Type: application/json
Accept-Language: <iso_language_code>
x-csrftoken: <token>

Body Parameters

Property	Data Type	Required	Description
uid	String	True	The user ID, encoded in Base64, used as part of the password reset confirmation process.
token	String	True	The unique token sent to the user's email for confirming password reset.
new_password1	String	True	The new password the user wants to set, which must comply with the password validation rules.
new_password2	String	True	Confirmation of the new password, which must match `new_password1`.

Request Body

{
    "uid": "MjM1",
    "token": "6w7-125c153fa562fcd3887e",
    "new_password1": "NewPassword123!",
    "new_password2": "NewPassword123!"
}

Example Request

import requests
import json

url = "https://{commerce_url}/rest-auth/password/reset/confirm/"

headers = {
  'Content-Type': 'application/json',
  'Accept-Language': '<iso_language_code>'
}

payload = json.dumps({
    "uid": "MjM1",
    "token": "6w7-125c153fa562fcd3887e",
    "new_password1": "NewPassword123!",
    "new_password2": "NewPassword123!"
})

response = requests.post(url, headers=headers, data=payload)
print(response.text)

Example Response (200 OK)

{
    "success": "Password has been reset with the new password."
}

Example Response (400 Bad Request)

If the passwords do not match:

{
    "new_password2": [
        "The two password fields didn't match."
    ]
}

If the token is invalid or expired:

{
    "token": [
        "Invalid value"
    ]
}

If the UID is invalid:

{
    "uid": [
        "Invalid value"
    ]
}

If the password does not match the validation rules:

{
    "new_password1": ["This password is too short. It must contain at least 8 characters."]
}

`GET` Password Reset Confirmation Page

This endpoint serves an HTML page informing users that their password reset process has been successfully completed. The page includes a link to the login page, where users can log in using their new password.

The login URL can be configured by using the LOGIN_URL Django project setting. By default, the login URL is /login/.

Path: /users/reset/done/

Authentication Required: No

Headers:

Content-Type: application/json
Accept-Language: <iso_language_code>

Example Request

import requests
import json

url = "https://{commerce_url}/users/reset/done/"

headers = {
  'Content-Type': 'application/json',
  'Accept-Language': '<iso_language_code>'
}

response = requests.get(url, headers=headers)
print(response.text)

Example Response (200 OK)

HTML file is returned for informing the user of a successful password reset and provides a link to the login page.

`POST` Password Reset Request with Phone Number

This endpoint enables users to request a password reset by providing their registered phone number. If the phone number matches an active user account, a password reset SMS will be sent.

Path: /users/password/reset-with-phone/

Authentication Required: No

Headers:

Content-Type: application/json
Accept-Language: <iso_language_code>
x-csrftoken: <token>

Body Parameters

Property	Data Type	Required	Description
phone	String	True	The phone number associated with the user account.

Request Body

{
    "phone": "1234567890"
}

Example Request

import requests
import json

url = "https://{commerce_url}/users/otp-login/"

headers = {
  'Content-Type': 'application/json',
  'Accept-Language: '<iso_language_code>',
  'x-csrftoken': '<token>'
}

payload = json.dumps({
    "phone": "1234567890"
})

response = requests.post(url, headers=headers, data=payload)
print(response.text)

Example Response (200 OK)

{
    "success": "If the phone number you specified is registered, a password reset sms has been sent."
}

`POST` Set Password with SMS OTP

This endpoint enables authenticated users to set or reset their password through SMS OTP verification. The process involves validating the user's phone number, with the option to resend the OTP if necessary.

To send SMS messages, the SMS_GATEWAY dynamic setting must be properly configured.

Path: /users/password-sms-otp/set/

Authentication Required: Yes

Headers:

Content-Type: application/json
Accept-Language: <iso_language_code>
x-csrftoken: <token>
Cookie: <cookie-name>=<session_id>

Body Parameters

Property	Data Type	Required	Description
password1	String	True	The new password for the user.
password2	String	True	Confirmation of the new password, which must match `password1.`
phone	String	True	The user's phone number, which must be unique and validated using a regex pattern.
code	String	False	The SMS verification code used for confirming the phone number.
resend	Boolean	False	A flag indicating whether the SMS verification code should be resent. Defaults to `false`.

NOTE

Sending only the phone number in the request body triggers the system to send an OTP code.
Providing both the phone number and OTP code in the request body initiates OTP verification.

Request Body

{
    "password1": "SecurePassword123",
    "password2": "SecurePassword123",
    "phone": "+1234567890",
    "code": "123456"
}

Example Request

import requests
import json

url = "https://{commerce_url}/users/otp-login/"

headers = {
  'Content-Type': 'application/json',
  'Accept-Language': '<iso_language_code>',
  'x-csrftoken': '<token>'
}

payload = json.dumps({
    "password1": "SecurePassword123",
    "password2": "SecurePassword123",
    "phone": "+1234567890",
    "code": "123456"
})

response = requests.post(url, headers=headers, data=payload)
print(response.text)

Example Response (200 OK)

{
    "messsage": "New password has been saved."
}

Example Response (202 Accepted)

{
    "password1": "SecurePassword123",
    "password2": "SecurePassword123",
    "phone": "+1234567890",
    "code": "123456"
}

Example Response (406 Not Acceptable)

{
    "non_field_errors": "Sms otp code expired. Please resend code.",
    "error_code": "sms_verification_100_4"
}

{
    "non_field_errors": "Phone numbers do not match.",
    "error_code": "sms_verification_100_1"
}

{
    "non_field_errors": "Verification codes do not match.",
    "error_code": "sms_verification_100_2"
}

`POST` User OTP Login

This endpoint allows users to log in using an OTP (One-Time Password) sent to their registered phone number. The user must provide their phone number, and optionally the OTP code to verify the login. For OTP login to function, PhoneNumberAuthenticationBackend must be included in the AUTHENTICATION_BACKENDS environment variable.

Path: /users/otp-login

Authentication Required: True

Headers:

Content-Type: application/json
Accept-Language: <iso_language_code>
x-csrftoken: <token>

Body Parameters

Property	Data Type	Required	Description
phone	String	True	The phone number registered in the system to which the OTP will be sent.
code	String	False	The OTP code sent to the user's phone. If provided, it will be verified.
resend	Boolean	False	If `true`, a new OTP code will be sent to the user's phone.

NOTE

Sending only the phone number in the request body will trigger the OTP code to be sent. If both the phone number and OTP code are provided, the code will be verified, and the user will be logged in upon successful verification.

Request Body

{
    "phone": "5300000000",
    "code": "12345"
}

Example Request

import requests
import json

url = "https://{commerce_url}/users/otp-login/"

headers = {
  'Content-Type': 'application/json',
  'Accept-Language: '<iso_language_code>',
  'x-csrftoken': '<token>'
}

payload = json.dumps({
    "phone": "5300000000",
    "code": "12345"
})

response = requests.post(url, headers=headers, data=payload)
print(response.text)

Example Response (302 Found)

{}

Example Response (400 Bad Request)

{
    "phone": [
        "This field is required."
    ]
}

`POST` User Passwordless Login with Token

This endpoint allows users to log in without a password by using a valid Django REST Framework authentication token. The token must be associated with an active user. Upon successful login, a session is created for the user, allowing them to remain logged in until they log out or the session expires.

Path: /users/passwordless-login-with-token/

Authentication Required: No

Headers:

Content-Type: application/json
Accept-Language: <iso_language_code>
x-csrftoken: <token>

Body Parameters

Property	Data Type	Required	Description
user	Integer	True	The ID of the user attempting to log in.
token	String	True	The Django REST Framework authentication token, which must be valid and associated with an active user.

Request Body

{
    "user": 123,
    "token": "9944b09199c62bcf9418ad846dd0e4bbdfc6ee4b"
}

Example Request

import requests
import json

url = "https://{commerce_url}/users/passwordless-login"

headers = {
  'Content-Type': 'application/json',
  'Accept-Language': '<iso_language_code>',
  'x-csrftoken': '<token>'
}

payload = json.dumps({
    "user": 123,
    "token": "abc123token"
})

response = requests.post(url, headers=headers, data=payload)
print(response.text)

Example Response (200 OK)

{}

Example Response (400 Bad Request)

If the token is invalid or the user ID does not exist:

{}

`GET` User Passwordless Login with One-Time Token

This endpoint allows users to log in without a password by clicking a link containing a one-time token generated by the Commerce OneTimeTokenGenerator. After the token is verified, the user is redirected to a specified URL or a default destination.

Path: /users/passwordless-login/<token>/

Authentication Required: No

Headers:

Content-Type: application/json
Accept-Language: <iso_language_code>
x-csrftoken: <token>

Query Parameters

Property	Data Type	Required	Description
user	Integer	True	The ID of the user attempting to log in.
secret_key	String	True	The secret key used to validate the one-time token.
next	String	False	The URL to redirect to after successful login, defaulting to the home page if not specified.

Example Request

import requests
import json

url = "https://{commerce_url}/users/passwordless-login/15jz-595a80d325b1a15a7b9f/?user=414179&secret_key=testsecretkey&next=/dashboard"

headers = {
  'Content-Type': 'application/json',
  'Accept-Language': '<iso_language_code>',
  'x-csrftoken': '<token>'
}

payload = json.dumps({
    "phone": "1234567890",
    "code": "12345"
})

response = requests.post(url, headers=headers, data=payload)
print(response.text)

Example Response (302 Redirect)

If the login is successful, the user is redirected to the specified next URL or the default home page.

{}

POST Set New Password​

Body Parameters​

Request Body​

Example Request​

Example Response (200 OK)​

Example Response (302 Redirect)​

Example Response (400 Bad Request)​

POST Change Password​

Body Parameters​

Request Body​

Example Request​

Example Response (200 OK)​

Example Response (400 Bad Request)​

POST Initiate Password Reset​

Body Parameters​

Request Body​

Example Request​

Example Response (200 OK)​

Example Response (400 Bad Request)​

GET Validate Password Reset URL​

Example Request​

Example Response (200 OK)​

Response Parameters​

POST Complete Password Reset with JSON Response​

Body Parameters​

Request Body​

Example Request​

Example Response (200 OK)​

Example Response (400 Bad Request)​

POST Complete Password Reset with HTML Response​

Body Parameters​

Request Body​

Example Request​

Example Response (200 OK)​

POST Confirm Password Reset​

Body Parameters​

Request Body​

Example Request​

Example Response (200 OK)​

Example Response (400 Bad Request)​

GET Password Reset Confirmation Page​

Example Request​

Example Response (200 OK)​

POST Password Reset Request with Phone Number​

Body Parameters​

Request Body​

Example Request​

Example Response (200 OK)​

POST Set Password with SMS OTP​

Body Parameters​

NOTE

Request Body​

Example Request​

Example Response (200 OK)​

Example Response (202 Accepted)​

Example Response (406 Not Acceptable)​

POST User OTP Login​

Body Parameters​

NOTE

Request Body​

Example Request​

Example Response (302 Found)​

Example Response (400 Bad Request)​

POST User Passwordless Login with Token​

Body Parameters​

Request Body​

Example Request​

Example Response (200 OK)​

Example Response (400 Bad Request)​

GET User Passwordless Login with One-Time Token​

Query Parameters​

Example Request​

Example Response (302 Redirect)​

`POST` Set New Password

Body Parameters

Request Body

Example Request

Example Response (200 OK)

Example Response (302 Redirect)

Example Response (400 Bad Request)

`POST` Change Password

Body Parameters

Request Body

Example Request

Example Response (200 OK)

Example Response (400 Bad Request)

`POST` Initiate Password Reset

Body Parameters

Request Body

Example Request

Example Response (200 OK)

Example Response (400 Bad Request)

`GET` Validate Password Reset URL

Example Request

Example Response (200 OK)

Response Parameters

`POST` Complete Password Reset with JSON Response

Body Parameters

Request Body

Example Request

Example Response (200 OK)

Example Response (400 Bad Request)

`POST` Complete Password Reset with HTML Response

Body Parameters

Request Body

Example Request

Example Response (200 OK)

`POST` Confirm Password Reset

Body Parameters

Request Body

Example Request

Example Response (200 OK)

Example Response (400 Bad Request)

`GET` Password Reset Confirmation Page

Example Request

Example Response (200 OK)

`POST` Password Reset Request with Phone Number

Body Parameters

Request Body

Example Request

Example Response (200 OK)

`POST` Set Password with SMS OTP

Body Parameters

Request Body

Example Request

Example Response (200 OK)

Example Response (202 Accepted)

Example Response (406 Not Acceptable)

`POST` User OTP Login

Body Parameters

Request Body

Example Request

Example Response (302 Found)

Example Response (400 Bad Request)

`POST` User Passwordless Login with Token

Body Parameters

Request Body

Example Request

Example Response (200 OK)

Example Response (400 Bad Request)

`GET` User Passwordless Login with One-Time Token

Query Parameters

Example Request

Example Response (302 Redirect)