chore: merge pull request #1300 from logto-io/rany-optimize-20051118

chore: optimize some docs

Author: Rany0101

docs/end-user-flows/one-time-token.mdx

@@ -228,6 +228,6 @@ There are a number of possible scenarios:
 2. The user is already signed in, and then clicks a magic link that associates with a different account. In this case, Logto will prompt the user to continue as the new account, or go back to the application with the current account.
    1. If the user chooses to continue as the new account, Logto will switch to the new account after the token verification is successful.
    2. If the user chooses to stick to the current account, Logto will not verify the token and return to the application with the current account.
-3. If your sign-in prompt is set to "login" or contains "login", Logto will automatically sign-in the account associated with the one-time token without prompting switch.
+3. If your sign-in prompt is set to "login" or contains "login", Logto will automatically sign-in the account associated with the one-time token without prompting switch. This is because the "login" prompt indicates an explicit intent to authenticate, which takes precedence over the current session.
 
 </details>

docs/end-user-flows/organization-experience/invite-organization-members.mdx

@@ -57,21 +57,15 @@ A sample email template for the `OrganizationInvitation` usage type is shown bel
 
 ```json
 {
-  "subject": "Welcome to my organization",
-  "content": "<p>Join {{organization.name}} by this <a href=\"{{link}}\" target=\"_blank\">link</a>.</p>",
+  "subject": "You're invited to join {{organization.name}}",
+  "content": "<p>Hi there,</p><p>{{inviter.name}} ({{inviter.primaryEmail}}) has invited you to join <strong>{{organization.name}}</strong>.</p><p>Click this <a href=\"{{link}}\" target=\"_blank\">link</a> to accept the invitation and get started.</p><p>If you weren't expecting this invitation, you can safely ignore this email.</p>",
   "usageType": "OrganizationInvitation",
   "type": "text/html"
 }
 ```
 
 The `{{link}}` placeholder in the email content will be replaced with the actual invitation link when the email is sent.
 
-:::note
-
-Logto Cloud’s built‑in “Logto email service” doesn’t currently support the `OrganizationInvitation` usage type. Configure your own email connector (e.g., SendGrid) and set up the `OrganizationInvitation` template instead.
-
-:::
-
 ## Handle invitations with Logto Management API \{#handle-invitations-with-logto-management-api}
 
 :::note

docs/security/blocklist.md docs/security/blocklist.mdxdocs/security/blocklist.md renamed to docs/security/blocklist.mdx

@@ -6,21 +6,21 @@ sidebar_position: 3
 
 # Blocklist
 
-## Email blocklist {#email-blocklist}
+## Email blocklist \{#email-blocklist}
 
 The email blocklist policy allows customization of email blocklist settings to prevent account sign-up abuse. It monitors email addresses used for sign-up and account settings. If a user attempts to sign up or link an email address that violates any blocklist rules, the system will reject the request, helping to mitigate spam accounts and enhance overall account security.
 
 Visit the <CloudLink to="/security/blocklist"> Console > Security > Blocklist</CloudLink> to configure the email blocklist settings.
 
-### Block disposable email addresses {#block-disposable-email-addresses}
+### Block disposable email addresses \{#block-disposable-email-addresses}
 
 This is a **cloud-only** feature. Once enabled, the system will automatically validates the domain of the provided email address against a list of known disposable email domains. If the domain is found in the list, the request will be rejected. The list of disposable email domains is regularly updated to ensure its effectiveness.
 
-### Block email subaddressing {#block-email-subaddressing}
+### Block email subaddressing \{#block-email-subaddressing}
 
 Email subaddressing allows users to create variations of their email addresses by adding a plus sign (+) followed by additional characters (e.g., [email protected]). This feature can be exploited by malicious users to bypass blocklist restrictions. By enabling the block email subaddressing feature, the system will reject any sign-up or account linking attempts that utilize subaddressed email formats.
 
-### Custom email blocklist {#custom-email-blocklist}
+### Custom email blocklist \{#custom-email-blocklist}
 
 You can create a custom email blocklist by specifying a list of email addresses or domains to block. The system will reject any sign-up or account linking attempts that match these entries. The blocklist supports both full email address and domain matching.
 
@@ -35,6 +35,8 @@ Disposable emails, subaddressing, and custom email are restricted during [new-us
 
 :::
 
-## Related resources {#related-resources}
+## Related resources \{#related-resources}
 
-<Url href="https://blog.logto.io/disposable-email">What is disposable email? How to handle them in your app?</Url>
+<Url href="https://blog.logto.io/disposable-email">
+  What is disposable email? How to handle them in your app?
+</Url>

docs/security/identifier-lockout.mdx

@@ -6,22 +6,22 @@ sidebar_position: 4
 
 # Identifier lockout
 
-## Sentinel \{#sentinel}
+The identifier lockout policy allows you to customize your own sentinel policy settings to protect against brute force access. This policy works by monitoring authentication attempts for each identifier (such as usernames or email addresses) and implementing restrictions when suspicious activity is detected. If a user exceeds the allowed number of failed authentication attempts, the system temporarily locks the identifier, preventing further authentication attempts for a specified duration. This helps to mitigate brute-force attacks and enhances overall account security.
 
-The identifier lockout policy allows you to customize your own sentinel policy settings to protect against account sign-in/sign-up abuse. This policy works by monitoring authentication attempts for each identifier (such as usernames or email addresses) and implementing restrictions when suspicious activity is detected. If a user exceeds the allowed number of failed authentication attempts, the system temporarily locks the identifier, preventing further authentication attempts for a specified duration. This helps to mitigate brute-force attacks and enhances overall account security.
-
-Visit the <CloudLink to="/security/general"> Console > Security > General</CloudLink> to configure the identifier lockout settings.
-
-## Applicaiton of the policy \{#applicaiton-of-the-policy}
-
-The identifier lockout (sentinel) policy will be applied in the following user interaction flows:
+## Application of the policy \{#application-of-the-policy}
 
 - **Identifier sign-in**: Password and verification code
 - **Identifier sign-up**: Email/phone verification code
 - **Reset password**: Email/phone verification code
 
 ## Policy settings \{#policy-settings}
 
+By default, an identifier is locked for 60 minutes after 100 failed authentication attempts.
+
+To customize the policy settings or manually unblock verified users, visit <CloudLink to="/security/general">Console > Security > General</CloudLink> and enable "Customize lockout experience".
+
+Configure the following settings:
+
 1. **Maximum failed attempts**:
 
    - Limit the number of consecutive failed authentication attempts per identifier within an hour. If the limit is exceeded, the identifier will be temporarily locked out.
@@ -32,5 +32,17 @@ The identifier lockout (sentinel) policy will be applied in the following user i
    - Block all authentication attempts for the given identifier for a specified period after exceeding the maximum failed attempts.
    - **Default Value**: 60 minutes
 
-3. **Manual unblock**:
+3. **Manual unblock**
+
    - Administrators can manually unblock users by providing a list of identifiers that need to be released from the lockout. The given identifiers must be precisely matched with the identifiers being blocked.
+
+## Lockout webhook \{#lockout-webhook}
+
+When an identifier is locked due to exceeding the maximum failed attempts, Logto triggers the `Identifier.Lockout` webhook event, enabling automated responses to suspicious account activity.
+
+**Common use cases:**
+
+- Send security alerts to your team for immediate review
+- Notify users via SMS or push notification about the lockout and provide recovery instructions
+
+Navigate to <CloudLink to="/webhooks">Console > Webhooks</CloudLink> to configure your webhook. For detailed event structure and configuration, see [Webhooks](/developers/webhooks).