diff --git a/docs/end-user-flows/account-settings/by-account-api.mdx b/docs/end-user-flows/account-settings/by-account-api.mdx
index 4c7eea52e33..40c22a51f7f 100644
--- a/docs/end-user-flows/account-settings/by-account-api.mdx
+++ b/docs/end-user-flows/account-settings/by-account-api.mdx
@@ -219,6 +219,10 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/password \
--data-raw '{"password":"..."}'
```
+:::tip
+Just like passwords created during sign-up, passwords set through the Account API must comply with the [password policy](/security/password-policy) you configured in Console > Security > Password policy. Logto returns detailed validation results and error messages if the password fails the policy.
+:::
+
### Update or link new email \{#update-or-link-new-email}
:::note
@@ -255,6 +259,10 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
--data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}'
```
+:::tip
+Just like emails collected during sign-up, any email linked through the Account API must pass the [blocklist](/security/blocklist) verification you configured in Console > Security > Blocklist. Logto will reject the request and return a detailed error if the email violates the policy.
+:::
+
### Remove the user's email \{#remove-the-users-email}
To remove the user's email, you can use the [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail) endpoint.
diff --git a/docs/security/blocklist.md b/docs/security/blocklist.md
index 5042bfe262d..50128664fbb 100644
--- a/docs/security/blocklist.md
+++ b/docs/security/blocklist.md
@@ -28,10 +28,10 @@ For instance, adding `@example.com` to the blocklist will block all email addres
:::note
-Disposable emails, subaddressing, and custom email are restricted during registration and account linking. Existing users with these email addresses can still sign in.
+Disposable emails, subaddressing, and custom email are restricted during [new-user registration](/end-user-flows/sign-up-and-sign-in/sign-up), [linking email during social sign-in](/end-user-flows/sign-up-and-sign-in/social-sign-in#collect-sign-up-identifiers), and updating emails via [Account API](/end-user-flows/account-settings/by-account-api#update-or-link-new-email). Existing users with these email addresses can still sign in.
- Admins can "bypass restrictions" by manually adding users in Console > User management, or via [Management API](https://openapi.logto.io/operation/operation-createuser). E.g., Create an user with a subaddress email when subaddressing is blocked.
-- Block exsiting accounts by deleting or suspending them in Console > User management.
+- Block existing accounts by deleting or suspending them in Console > User management.
:::
diff --git a/docs/security/password-policy.mdx b/docs/security/password-policy.mdx
index 3f52ee1d14e..0c3cbb12dbc 100644
--- a/docs/security/password-policy.mdx
+++ b/docs/security/password-policy.mdx
@@ -6,6 +6,12 @@ sidebar_position: 1
# Password policy
+Logto applies the password policy in different ways depending on how the password is created or updated:
+
+- End-user flows such as [the out-of-the-box sign-in experience](/end-user-flows/sign-up-and-sign-in/sign-up), [the Experience API](/customization/bring-your-ui), and [the Account API](/end-user-flows/account-settings/by-account-api#update-users-password) always enforce the current [password policy](#set-up-password-policy).
+- Administrator actions via the Management API [`patch /api/users/{userId}/password`](https://openapi.logto.io/operation/operation-updateuserpassword) are exempt, allowing you to provision or reset credentials without policy checks when needed.
+- To audit existing passwords against the current rules, call [`POST /api/sign-in-exp/default/check-password`](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) and act on the returned validation result. Read [Password compliance check](#password-compliance-check) to learn more.
+
## Set up password policy \{#set-up-password-policy}
For new users or users who are updating their password, you can set a password policy to enforce password strength requirements. Visit the Console > Security > Password policy to configure the password policy settings.
@@ -25,8 +31,11 @@ For new users or users who are updating their password, you can set a password p
After you update the password policy in Logto, existing users can still sign in with their current passwords. Only newly created account will be required to follow the updated policy.
-To enforce stronger security, you can use the `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) to check whether a user's password meets the current policy defined in the default sign-in experience. If it doesn't, you can prompt the user to update their password with a custom flow using [Account API](/end-user-flows/account-settings/by-management-api#user-password-management).
+To enforce stronger security, you can use the `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) to check whether a user's password meets the current policy defined in the default sign-in experience. If it doesn't, you can prompt the user to update their password with a custom flow using [Account API](/end-user-flows/account-settings/by-account-api).
## Related resources \{#related-resources}
+Manage users
+Sign-up and sign-in
+Account settings by Account API
Design your password policy
diff --git a/docs/user-management/manage-users.mdx b/docs/user-management/manage-users.mdx
index 5313a240fb8..4c83cd9ccba 100644
--- a/docs/user-management/manage-users.mdx
+++ b/docs/user-management/manage-users.mdx
@@ -88,6 +88,12 @@ After you reset the password, copy and send it to the end-user. Once the "Reset
You cannot set a specific password for users in the Logto Console, but you can use the [Management API](/integrate-logto/interact-with-management-api) `PATCH /api/users/{userId}/password` to specify a password.
+## Password compliance check \{#password-compliance-check}
+
+After you update the [password policy](/security/password-policy) in Logto, existing users can still sign in with their current passwords. Only newly created accounts will be required to follow the updated password policy.
+
+To enforce stronger security, you can use the `POST /api/sign-in-exp/default/check-password` [API](https://openapi.logto.io/operation/operation-checkpasswordwithdefaultsigninexperience) to check whether a user's password meets the current policy defined in the default sign-in experience. If it doesn't, you can prompt the user to update their password with a custom flow using [Account API](/end-user-flows/account-settings/by-management-api#user-password-management).
+
### Manage roles of users \{#manage-roles-of-users}
In the "Roles" tab of the user details page, you can easily assign or remove roles to meet your desired outcome. Check [Role-based access control](/authorization/role-based-access-control) for details.