chore: merge pull request #1293 from logto-io/rany-account-api-security-policy

chore: account api security policy

Author: Rany0101

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 <CloudLink to="/security/password-policy">Console > Security > Password policy</CloudLink>. 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 <CloudLink to="/security/blocklist">Console > Security > Blocklist</CloudLink>. 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.

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 <CloudLink to="/users">Console > User management</CloudLink>, 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 <CloudLink to="/users">Console > User management</CloudLink>.
+- Block existing accounts by deleting or suspending them in <CloudLink to="/users">Console > User management</CloudLink>.
 
 :::
 

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 <CloudLink to="/security/password-policy"> Console > Security > Password policy</CloudLink> 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}
 
+<Url href="/user-management/manage-users">Manage users</Url>
+<Url href="/end-user-flows/sign-up-and-sign-in">Sign-up and sign-in</Url>
+<Url href="/end-user-flows/account-settings/by-account-api">Account settings by Account API</Url>
 <Url href="https://blog.logto.io/design-your-password-policy">Design your password policy</Url>

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.