First Login - Mandatory Password Change

Brands can require customers created or imported with default credentials to set a personal password on their first login. This page describes how to detect that state after login and how to complete the mandatory password change.

How the Flow Works

1. Login with the default password. The login succeeds (201, token_created) and returns the access token plus the customer payload. The "must change password" signal is customer.passwordExpiresAt being in the past.
2. Detect the expired password. While it is expired, every other customer-scoped endpoint returns 401 password_expired. Send the customer to your password-change screen.
3. Set the new password with PUT /customers/{customerId}/reset_password, authenticated with the same Bearer token obtained at login.
4. Continue the session. On success, passwordExpiresAt is cleared and the existing token remains valid - no re-login is needed.

Step 1 - Login with the Default Password

{
  "username": "john.doe@company.com",
  "password": "12345",
  "brandId": 496,
  "grant_type": "password"
}

{
  "status": 201,
  "code": "token_created",
  "message": "You have successfully logged in.",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1...",
    "tokenType": "Bearer",
    "customer": {
      "customerId": 5337578,
      "brandId": 496,
      "email": "john.doe@company.com",
      "firstName": "John",
      "lastName": "Doe",
      "badgeNumber": "0012345",
      "passwordExpiresAt": "2026-01-05T09:00:00.000Z"
    }
  }
}

Step 2 - Expired Password Blocks Every Other Call

While passwordExpiresAt is in the past, every other customer-scoped endpoint (profile, balance, ordering, ...) responds HTTP 401 with code password_expired. Retrying the login without changing the password keeps succeeding (201) and keeps returning the past passwordExpiresAt.

{
    "status": 401,
    "code": "password_expired",
    "message": "Your password has expired."
}

Step 3 - Set the New Password

Call the reset endpoint with the same Bearer token obtained at login - this endpoint explicitly accepts tokens of customers whose password is expired. No old password is required: the proof is that the account is in the expired state.

{
  "customerId": 5337578,
  "newPassword": "MyNewPassw0rd!"
}

{
  "status": 200,
  "code": "forgottenPassword_retrieve",
  "message": "Password updated successfully."
}

On success (200) the server stores the new password and clears passwordExpiresAt. The token issued at login remains valid: keep the session and continue - all customer endpoints work normally from this point, and subsequent logins with the new password no longer trigger the flow.

Password Requirements

The new password must satisfy the following policy:

• Minimum 12 characters (maximum 50)
• At least one lowercase letter
• At least one uppercase letter
• At least one digit
• At least one special character

This is the API's securedPassword rule:

^(?=.*[0-9])(?=.*[a-z])(?=.*[A-Z])(?=.*[!@#$%^&*()\[\]{}€£?_;.:,\-+='"~<>]).{12,50}$

Error Reference