diff --git a/docs/kratos/_static/manage-identities/import-user-accounts-identities/pw-migration-pending-badge.png b/docs/kratos/_static/manage-identities/import-user-accounts-identities/pw-migration-pending-badge.png
new file mode 100644
index 0000000000..3f5dbf2d06
Binary files /dev/null and b/docs/kratos/_static/manage-identities/import-user-accounts-identities/pw-migration-pending-badge.png differ
diff --git a/docs/kratos/_static/manage-identities/import-user-accounts-identities/pw-migration-webhook-step-1.png b/docs/kratos/_static/manage-identities/import-user-accounts-identities/pw-migration-webhook-step-1.png
new file mode 100644
index 0000000000..5ffce83e10
Binary files /dev/null and b/docs/kratos/_static/manage-identities/import-user-accounts-identities/pw-migration-webhook-step-1.png differ
diff --git a/docs/kratos/_static/manage-identities/import-user-accounts-identities/pw-migration-webhook-step-2.png b/docs/kratos/_static/manage-identities/import-user-accounts-identities/pw-migration-webhook-step-2.png
new file mode 100644
index 0000000000..8b404d9ad5
Binary files /dev/null and b/docs/kratos/_static/manage-identities/import-user-accounts-identities/pw-migration-webhook-step-2.png differ
diff --git a/docs/kratos/_static/manage-identities/import-user-accounts-identities/pw-migration-webhook-table.png b/docs/kratos/_static/manage-identities/import-user-accounts-identities/pw-migration-webhook-table.png
new file mode 100644
index 0000000000..2c57538e89
Binary files /dev/null and b/docs/kratos/_static/manage-identities/import-user-accounts-identities/pw-migration-webhook-table.png differ
diff --git a/docs/kratos/manage-identities/25_import-user-accounts-identities.mdx b/docs/kratos/manage-identities/25_import-user-accounts-identities.mdx
index 51cc55af58..8292f46e5f 100644
--- a/docs/kratos/manage-identities/25_import-user-accounts-identities.mdx
+++ b/docs/kratos/manage-identities/25_import-user-accounts-identities.mdx
@@ -7,6 +7,12 @@ toc_max_heading_level: 3
# Import identities
+```mdx-code-block
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import BrowserWindow from "@site/src/theme/BrowserWindow"
+```
+
Ory allows you to import identities from any other system. To import identities, you use the same endpoint as for
[creating identities](./20_create-users-identities.mdx). The main difference between creating and importing identities is that
when you import identities, you must provide the `credentials` field.
@@ -45,9 +51,6 @@ This is a sample payload for importing an identity with a verified address:
Test the above example with a cURL command:
````mdx-code-block
-import Tabs from '@theme/Tabs'
-import TabItem from '@theme/TabItem'
-
+
+ ```
+
+ a. Go to your project in the [Ory Console](https://console.ory.sh).
+
+ b. Click **Authentication** in the top navigation bar.
+
+ c. Click **Actions & Webhooks** in the left sidebar.
+
+ d. Click **Create new Action**.
+
+ e. In the **Action Base Details** dialog, fill in the following fields:
+
+ - **Flow** — Select **Password Migration**. The execution phase and method fields are hidden because the migration hook runs
+ at login time automatically, outside of the standard flow lifecycle.
+
+ - **URL** — Enter the URL of your password migration webhook endpoint, for example `https://example.org/migrate-password`.
+
+ - **Method** — Select the HTTP method your endpoint expects, for example **POST**.
+
+ - **Action HTTP body** — The body is pre-filled with a Jsonnet template that maps `ctx.identifier` and `ctx.password` to the
+ request payload. You can customize it. See the
+ [webhook documentation](../../guides/integrate-with-ory-cloud-through-webhooks.mdx#customizing-request-body-with-jsonnet)
+ for all available context fields.
+
+ ```mdx-code-block
+
+ 
+
+ ```
+
+ f. Click **Next** to proceed to the **Action authentication** step. Select the authentication type for your webhook endpoint.
+ Ory supports **None**, **Basic** (username and password), and **Key** (API key in a header or cookie). See the
+ [webhook authentication documentation](../../guides/integrate-with-ory-cloud-through-webhooks.mdx#request-authentication) for
+ details on each option.
+
+ :::warning
+
+ Leaving your webhook endpoint unauthenticated exposes it to unauthorized access. Secure your endpoint with strong
+ authentication to protect sensitive credentials passed during migration.
+
+ :::
+
+ ```mdx-code-block
+
+ 
+
+ ```
+
+ g. Click **Save action**. The new **Password Migration** action appears in the actions table.
+
+ ```mdx-code-block
+
+ 
+
+ ```
+
+ ```mdx-code-block
+
+
+ ```
+
Add the web hook URL to the configuration. See the
[web hook configuration](../../guides/integrate-with-ory-cloud-through-webhooks.mdx#request-authentication) for authentication
options. If you use Ory Network, update this configuration directly using the
@@ -589,6 +661,11 @@ The following steps are necessary to set up password migration using a web hook:
}
```
+ ```mdx-code-block
+
+
+ ```
+
3. Implement the password migration web hook
If a user logs in and the identifier points to an identity that has `use_password_migration_hook` set to `true`, Ory
@@ -602,6 +679,27 @@ The following steps are necessary to set up password migration using a web hook:
}
```
+ To verify that an identity is pending migration in the Ory Console:
+
+ a. Go to your project in the [Ory Console](https://console.ory.sh).
+
+ b. Click **User management** in the top navigation bar.
+
+ c. Click **Users & identities** in the left sidebar.
+
+ d. Find the identity you want to review and click the three-dot menu (**⋮**) on its row.
+
+ e. Click **View identity** to open its details.
+
+ f. In the **Basic Information** section, under **Credential Identifiers**, the identity shows a **Migration pending** badge if
+ the user hasn't logged in and completed the password migration yet.
+
+ ```mdx-code-block
+
+ 
+
+ ```
+
The web hook can then check the identifier and password against the legacy system. If the password matches, the web hook must
respond with a `200 OK` status code and the following payload: