> For the complete documentation index, see [llms.txt](https://developer.emporix.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.emporix.io/ce/system-management/authentication-and-authorization/authentication/customer-authentication/password-migration-strategy.md).

# Password Migration Strategy

Password migration strategy lets you move customers from a legacy commerce system to Emporix without forcing a password reset. You import existing password hashes, customers log in with their current credentials, and Emporix upgrades each password to the native security format in the background.

{% hint style="info" %}

* Looking for API documentation? Check out the [Customer Service (Tenant Managed) Tutorial](/api-references/api-guides/companies-and-customers/customer-service/customer-service-tenant.md).
* To use custom email templates or storefront redirects, see [Mailjet](/ce/extensibility-and-integrations/integrations/communication-integration/mailjet.md) and contact the [Emporix Support Team](mailto:support@emporix.com).
  {% endhint %}

## Purpose

Password migration functionality is designed for platform migrations where you need to preserve the existing login experience, for example, when you move from a third party ERP system.

Emporix stores password hashes, not plain-text passwords. Emporix rehashes a password only when the customer logs in and submits it. Until that first successful login, Emporix verifies credentials against the imported legacy hash.

## Features

| Feature                       | Description                                                                                                                                                        |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Transparent lazy rehash**   | After the first successful login, Emporix converts the password to the native security format automatically. The customer does not take extra steps.               |
| **Legacy hashing algorithms** | Emporix verifies imported hashes with a registry of legacy methods, for example, Hybris SHA-512, during the retention window without changing the core login flow. |
| **Scoped batch import**       | A dedicated, scoped endpoint imports customers in batches of up to 200, including hashes and metadata, without sending welcome emails.                             |
| **Security parity**           | Login failures and lockout handling are the same for legacy and native authentication, so the migration window does not create a weaker path.                      |

Typical use cases:

* Moving from a legacy commerce system to Emporix while keeping the existing login experience
* Bringing customer data from acquired companies or other platforms that use different authentication methods into a single Emporix tenant

## How it works

The functionality has two stages:

<table data-card-size="large" data-view="cards"><thead><tr><th align="center"></th><th align="center"></th><th align="center"></th></tr></thead><tbody><tr><td align="center"><i class="fa-hourglass-end">:hourglass-end:</i></td><td align="center"><strong>Migration retention configuration</strong></td><td align="center">When imported accounts use a hashing mechanism other than the Emporix native format, configure a retention window. The configuration includes a retention end date and an optional reminder date. You can create or update the configuration with an upsert endpoint and remove it with a delete endpoint.</td></tr><tr><td align="center"><i class="fa-file-import">:file-import:</i></td><td align="center"><strong>Bulk customer import</strong></td><td align="center">Insert up to 200 customers per request, including legacy password hashes and related metadata such as salts. This import does not trigger extra onboarding logic, such as welcome emails.</td></tr></tbody></table>

You can configure retention yourself through the API. Emporix can also configure it on your behalf. To use custom email templates and storefront redirects, contact the [Emporix Support Team](mailto:support@emporix.com).

The retention timeline is as follows:

```mermaid
---
config:
  layout: fixed
  theme: base
  look: classic
  themeVariables:
    background: transparent
    lineColor: "#9CBBE3"
    arrowheadColor: "#9CBBE3"
    edgeLabelBackground: "#FFC128"
    edgeLabelTextColor: "#4C5359"
---
flowchart TD
    CONFIG(["SET RETENTION CONFIG"])
    IMPORT(["IMPORT CUSTOMERS WITH LEGACY HASHES"])
    SILENT(["SILENT PERIOD: FIRST LOGIN REHASHES"])
    REMINDER(["REMINDER EMAIL TO UNMIGRATED CUSTOMERS"])
    THANKYOU(["LOGIN AFTER REMINDER: THANK-YOU EMAIL"])
    ENDDATE(["RETENTION END: DELETE LEGACY HASHES"])
    RESET(["UNMIGRATED CUSTOMERS MUST RESET PASSWORD"])

    CONFIG --> IMPORT
    IMPORT --> SILENT
    SILENT --> REMINDER
    REMINDER --> THANKYOU
    REMINDER --> ENDDATE
    THANKYOU --> ENDDATE
    ENDDATE --> RESET

    CONFIG@{ shape: rounded }
    IMPORT@{ shape: rounded }
    SILENT@{ shape: rounded }
    REMINDER@{ shape: rounded }
    THANKYOU@{ shape: rounded }
    ENDDATE@{ shape: rounded }
    RESET@{ shape: rounded }

    CONFIG:::Class_03
    IMPORT:::Class_03
    SILENT:::Class_02
    REMINDER:::Class_01
    THANKYOU:::Class_01
    ENDDATE:::Class_03
    RESET:::Class_04

    classDef Class_01 stroke-width:1px, stroke:#4C5359, fill:#A1BDDC
    classDef Class_02 stroke-width:1px, stroke:#4C5359, fill:#DDE6EE
    classDef Class_03 stroke-width:1px, stroke:#4C5359, fill:#FFC128, color:#4C5359
    classDef Class_04 stroke-width:1px, stroke:#4C5359, fill:#F2F6FA
```

## Customer experience

{% stepper %}
{% step %}

#### Silent period

Until the reminder date, migration is silent. Customers who log in keep using their existing password. Emporix validates the password with the legacy method and rehashes it to the native format in the background. No email is sent.
{% endstep %}

{% step %}

#### Reminder to log in

On the reminder date, customers who have not logged in yet receive an email that asks them to log in. The email includes the deadline and states that they must reset their password if they do not log in before retention ends.

The reminder date is the date you set in the retention configuration. If you omit it, the default is one week before the retention end date.
{% endstep %}

{% step %}

#### Thank-you after a late login

A customer who logs in between the reminder email and the retention end date receives a thank-you email. The email confirms that they do not need to take further action. Customers who already logged in before the reminder do not receive this email.
{% endstep %}

{% step %}

#### Retention end

When the retention end date is reached:

* Emporix deletes the legacy hashes you imported. Only hashes in the native Emporix format remain.
* Customers who still have not logged in can no longer log in with the old password. They must reset their password.
* Those customers receive an email that tells them they must reset their password.
  {% endstep %}
  {% endstepper %}

## How to set up password migration

Configure the retention window and import customers with legacy hashes through the Customer Service tenant-managed APIs. For the endpoint sequence, scopes, and request examples, see the [Customer Service (Tenant Managed) Tutorial](/api-references/api-guides/companies-and-customers/customer-service/customer-service-tenant.md).

After import, the retention window runs automatically. See [Customer experience](#customer-experience) for the silent period, reminder and thank-you emails, and retention end.

{% hint style="success" %}
Contact the [Emporix Support Team](mailto:support@emporix.com) when you need assistance with:

* Changing the Mailjet templates for the login reminder, thank-you, or password-reset emails
* Adding storefront redirects so the reminder email opens the login page and the reset-required email opens the password-reset page

These emails are sent once during migration. Template and redirect changes are not self-service.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://developer.emporix.io/ce/system-management/authentication-and-authorization/authentication/customer-authentication/password-migration-strategy.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.