chore: update doc details from feedbacks (#1286)

Rany0101 · Copilot · web-flow · commit ead302377129 · 2025-11-04T11:27:20.000+08:00
* chore: update doc details from feedback

* chore: update docs/user-management/user-data.mdx

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

* chore: update docs/end-user-flows/authentication-parameters/first-screen.mdx

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;

---------

Co-authored-by: Copilot &lt;175728472+Copilot@users.noreply.github.com&gt;
diff --git a/docs/authorization/global-api-resources.mdx b/docs/authorization/global-api-resources.mdx
@@ -245,6 +245,36 @@ Use a [personal access token](/user-management/personal-access-token) to simulat
 
 </details>
 
+<details>
+<summary>
+
+### Can I use scope prefixes or shortened versions when requesting permissions? \{#can-i-use-scope-prefixes-or-shortened-versions}
+
+</summary>
+
+No. Scope names must **exactly match** the permission names defined in your API resource. Prefixes and shortened versions do not work as wildcards.
+
+**Example:**
+
+If your API resource defines:
+
+- `read:elections`
+- `write:elections`
+
+You must request:
+
+```swift
+scopes: ["read:elections", "write:elections"]
+```
+
+This will **NOT work**:
+
+```swift
+scopes: ["read", "write"]  // ❌ Doesn't match permission names
+```
+
+</details>
+
 ## Further reading \{#further-reading}
 
 <Url href="/authorization/validate-access-tokens">How to validate access tokens</Url>
diff --git a/docs/customization/localized-languages.mdx b/docs/customization/localized-languages.mdx
@@ -99,6 +99,19 @@ Suppose, that you only want to make adjustments to a subset of the original cont
 
 </details>
 
+<details>
+  <summary>
+
+### How can I set a default phone number country code for the sign-in experience? \{#how-can-i-set-a-default-phone-number-country-code-for-the-sign-in-experience}
+
+</summary>
+
+The phone number country code in the [sign-in experience](/end-user-flows/sign-up-and-sign-in/sign-up) defaults to the user's browser locale. For example, if a user's browser language is set to `fr`, the country code will default to France (+33).
+
+To programmatically control the default country code for specific users or regions, you can use the [`ui_locales`](/end-user-flows/authentication-parameters/ui-locales) authentication parameter. For instance, setting `ui_locales=ja` will default the country code to Japan (+81).
+
+</details>
+
 ## Related resources \{#related-resources}
 
 <Url href="https://blog.logto.io/rtl-language-support">
diff --git a/docs/end-user-flows/account-settings/by-account-api.mdx b/docs/end-user-flows/account-settings/by-account-api.mdx
@@ -353,7 +353,17 @@ curl -X PATCH https://[tenant-id].logto.app/api/account-center \
   --data-raw '{"webauthnRelatedOrigins":["https://account.example.com"]}'
 ```
 
-To learn more about the related origins, please refer to [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) documentation.
+:::note
+
+WebAuthn supports up to 5 unique eTLD+1 labels for Related Origins. The eTLD+1 (effective top-level domain plus one label) is the registrable domain portion. For example:
+
+- `https://example.com`, `https://app.example.com`, and `https://auth.example.com` count as **one** label (`example.com`)
+- `https://shopping.com`, `https://shopping.co.uk`, and `https://shopping.co.jp` also count as **one** label (`shopping`)
+- `https://example.com` and `https://another.com` count as **two** labels
+
+If you need to support more than 5 different domains as the Related Origins, refer to the [Related Origin Requests](https://passkeys.dev/docs/advanced/related-origins/) documentation for details.
+
+:::
 
 **Step 2: Request new registration options**
 
diff --git a/docs/end-user-flows/authentication-parameters/first-screen.mdx b/docs/end-user-flows/authentication-parameters/first-screen.mdx
@@ -14,12 +14,12 @@ A set to custom authentication parameters that allow you to tailor the desired f
 
 The `first_screen` parameter is the key parameter that determines the first screen that the users will see when they redirect to the Logto's sign-in page. By default, the universal sign-in form will be displayed. Use this parameter to customize the first screen based on your application's requirements. Supported values are:
 
-- `sign_in`: Displays the sign-in form. (Default)
+- `sign_in` (Default): Displays the sign-in form.
 - `register`: Displays the sign-up form.
 - `reset_password`: Displays the password reset form.
 - `single_sign_on`: Displays the enterprise SSO sign-in form. (A email address will be asked to determine the enabled SSO providers)
-- `identifier:sign-in`: Displays a identifier specific sign-in form. The identifier type can be specified using the `identifier` parameter. This is useful when you have multiple identifier sign-in methods enabled.
-- `identifier:register`: Displays a identifier specific sign-up form. The identifier type can be specified using the `identifier` parameter. This is useful when you have multiple identifier sign-up methods enabled.
+- `identifier:sign-in`: Displays a identifier specific sign-in form. The identifier type can be specified using the `identifier` parameter (optional). This is useful when you have multiple identifier sign-in methods enabled.
+- `identifier:register`: Displays a identifier specific sign-up form. The identifier type can be specified using the `identifier` parameter (optional). This is useful when you have multiple identifier sign-up methods enabled.
 
 <img src="/img/assets/first-screen-parameter.png" alt="First screen parameter" />
 
@@ -30,6 +30,10 @@ curl --location \
 --request GET 'https://<your-tenant>.logto.app/oidc/auth?client_id=<client_id>&...&first_screen=single_sign_on'
 ```
 
+:::tip
+The first screen will follow the settings configured in <CloudLink to="/sign-in-experience/branding">Console > Sign-in experience</CloudLink>. You need to enable the required authentication methods first, and configure branding, terms and privacy policies, and internationalization (i18n). Note that only the `sign-in` and `register` pages display the logo by default.
+:::
+
 ## identifier \{#identifier}
 
 The `identifier` parameter is used to specify the identifier types that the sign-in or sign-up form will take. This parameter is only applicable when the `first_screen` parameter is set to `identifier:sign-in`, `identifier:register`, or `reset_password`. Supported values are: `username`, `email`, and `phone`. Separate multiple values with a empty space to allow multiple identifier types.
diff --git a/docs/end-user-flows/authentication-parameters/ui-locales.mdx b/docs/end-user-flows/authentication-parameters/ui-locales.mdx
@@ -11,6 +11,7 @@ Logto supports the standard OIDC authentication parameter `ui_locales` to contro
 - Determines the UI language of the Logto-hosted sign-in experience at runtime. Logto picks the first language tag in `ui_locales` that is supported in your tenant's language library.
 - Affects email localization for messages triggered by the interaction (e.g., verification code emails). See [Email template localization](/connectors/email-connectors/email-templates#email-template-localization).
 - Exposes the original value to email templates as a variable `uiLocales`, allowing you to include it in the email subject/content if needed.
+- Sets the default phone number country code in the sign-in experience. For example, if `ui_locales=fr`, the phone number input field will default to France (+33). This is useful when you want to control the default country code programmatically for specific user groups or regions.
 
 ## Parameter format \{#parameter-format}
 
diff --git a/docs/end-user-flows/sign-up-and-sign-in/sign-in.mdx b/docs/end-user-flows/sign-up-and-sign-in/sign-in.mdx
@@ -36,7 +36,8 @@ If both factors are enabled, users can choose either method to complete the sign
 The sign-in experience adapts based on the chosen identifier and available authentication factors.
 
 - **Smart input for multiple identifiers:**
-  If more than one identifier sign-in method is enabled, Logto build-in sign-in page will automatically detect the type of identifier entered by the user and display the corresponding verification options. For example, if both **Email address** and **Phone number** are enabled, the sign-in page will automatically detect the type of identifier entered by the user and display the corresponding verification options. It switches to a phone number format with region code if numbers are entered consecutively or an email format when a “@” symbol is used.
+  If more than one identifier sign-in method is enabled, Logto build-in sign-in page will automatically detect the type of identifier entered by the user and display the corresponding verification options. For example, if both **Email address** and **Phone number** are enabled, the sign-in page will automatically detect the type of identifier entered by the user and display the corresponding verification options. It switches to a phone number format with region code if numbers are entered consecutively or an email format when a "@" symbol is used.
+  - The phone number country code defaults to the user's browser locale; users can switch manually. You can use the [`ui_locales`](/end-user-flows/authentication-parameters/ui-locales) parameter to set a specific default country code. See [Localized languages](/customization/localized-languages#how-can-i-set-a-default-phone-number-country-code-for-the-sign-in-experience) for more details.
 - **Enabled verification factors:**
   - **Password only:** Both identifier and password fields will be displayed on the first screen.
   - **Verification code only:** The identifier field appears on the first screen, followed by the verification code field on the second screen.
diff --git a/docs/end-user-flows/sign-up-and-sign-in/sign-up.mdx b/docs/end-user-flows/sign-up-and-sign-in/sign-up.mdx
@@ -25,6 +25,16 @@ If no identifiers are selected, it applies to the [social](/end-user-flows/sign-
 
 You can adjust the order of sign-up identifiers to prioritize the one you want users to provide first during sign-up. This order is reflected in the sign-up process, where the first identifier appears on the initial registration screen, and the rest are collected in subsequent steps.
 
+:::tip
+To block specific types of email addresses during sign-up (such as disposable emails, subaddressing with plus signs (+), specific email addresses, or entire domains), use the **blocklist** feature in the Security section. See [Blocklist](/security/blocklist) for more details.
+:::
+
+:::tip
+The phone number **country code** defaults to the user's browser locale. For example, if a user's browser language is set to `fr`, the country code will default to France (+33).
+
+You can also use the [`ui_locales`](/end-user-flows/authentication-parameters/ui-locales) authentication parameter to set the sign-in experience language, which will also determine the default country code.
+:::
+
 ## Set up the sign-up verification settings \{#set-up-the-sign-up-verification-settings}
 
 To ensure the security of the user sign-up and future sign-in process, you also need to configure the verification settings for the identifiers that you collect during the sign-up process. The available settings are:
diff --git a/docs/integrate-logto/application-data-structure.mdx b/docs/integrate-logto/application-data-structure.mdx
@@ -33,6 +33,10 @@ An _Application_ can be one of the following application types:
 
 _Application secret_ is a key used to authenticate the application in the authentication system, specifically for private clients (Traditional Web and M2M apps) as a private security barrier.
 
+:::tip
+Single Page Apps (SPAs) and Native apps don't provide App secret. SPAs and Native apps are "public clients" and cannot keep secrets (browser code or app bundles are inspectable). Instead of an app secret, Logto protects them with PKCE, strict redirect URI/CORS validation, short-lived access tokens, and refresh-token rotation.
+:::
+
 ### Application name \{#application-name}
 
 _Application name_ is a human-readable name of the application and will be displayed in the admin console.
diff --git a/docs/integrate-logto/integrate-logto-into-your-application/README.mdx b/docs/integrate-logto/integrate-logto-into-your-application/README.mdx
@@ -25,6 +25,21 @@ The guide in the console is only for quick start with Logto using our SDK. For c
    <Url href="/authorization">Authorization</Url>
    <Url href="/organizations">Organizations</Url>
 
+## FAQs
+
+<details>
+  <summary>
+    ### How can my backend service validate user tokens and manage users with Logto?
+  </summary>
+To securely validate access tokens in your backend API (e.g., Python, Node.js, Go, Java, PHP, etc.), and to programmatically manage users, please refer to the guide: [How to validate access tokens in your API service or backend](/authorization/validate-access-tokens).
+
+This documentation covers:
+
+- How to check the validity of bearer tokens in every API call
+- Best practices for integrating Logto with multiple frontend apps and a backend service
+
+</details>
+
 ## Related resources \{#related-resources}
 
 <Url href="https://blog.logto.io/complete-guide-to-integrating-oidc-server">
diff --git a/docs/integrate-logto/third-party-applications/README.mdx b/docs/integrate-logto/third-party-applications/README.mdx
@@ -22,8 +22,8 @@ Thus due to OIDC builds upon [OAuth 2.0](https://auth.wiki/oauth-2.0) adding an
 
 ## Create an third-party application in Logto \{#create-an-third-party-application-in-logto}
 
-1. Go to <CloudLink to="/applications">Console > Applications</CloudLink>
-2. Select "Third-party app" as the application type and choose one of the following integration protocols:
+1. Go to <CloudLink to="/applications">Console > Applications</CloudLink>.
+2. Click on the "Create application" button. Select "Third-party app" as the application type and choose one of the following integration protocols:
    - OIDC / OAuth
 3. Enter a name and description for your application and click on the “Create” button. A new third-party application will be created.
 
diff --git a/docs/logto-cloud/custom-domain.mdx b/docs/logto-cloud/custom-domain.mdx
@@ -75,6 +75,37 @@ If your domain is hosted on Cloudflare, disable the Cloudflare proxy for the CNA
 
 </details>
 
+<details>
+<summary>
+
+### "Redirect URI does not match" error after setting up custom domain \{#redirect-uri-mismatch}
+
+</summary>
+
+If you get a "redirect URI does not match" error after adding your custom domain, you need to update your SDK configuration to use the custom domain as the endpoint.
+
+**About "primary domain":**
+
+There is no separate "primary domain" setting in Logto. After adding a custom domain, both your custom domain and the default `{tenant-id}.logto.app` domain remain valid. The domain you configure in your SDK's `endpoint` parameter determines which domain will be used for authentication flows.
+
+**Solution:**
+
+Update the `endpoint` parameter in your SDK initialization to use your custom domain:
+
+```typescript
+const client = new LogtoClient({
+  endpoint: 'https://auth.example.com', // Use your custom domain
+  appId: 'your-app-id',
+  // ... other options
+});
+```
+
+Also verify that the redirect URIs registered in <CloudLink to="/applications">Console → Applications</CloudLink> match the domain you're using.
+
+**Note:** Logto automatically provisions and manages SSL certificates for your custom domain. You don't need to configure your own certificates.
+
+</details>
+
 ## Use custom domain \{#use-custom-domain}
 
 Once you've configured your settings, both your custom domain name and the default Logto domain name will be available for your tenant. However, certain configurations are required to activate your custom domain name.
diff --git a/docs/logto-oss/get-started-with-oss.mdx b/docs/logto-oss/get-started-with-oss.mdx
@@ -277,6 +277,10 @@ Please note that we do not provide customer support for third-party service prov
 
 Once you have successfully hosted Logto on your server, click on "Create account" on the welcome page. Keep in mind that the open-source version of Logto only allows for one account creation during the initial launch and does not support multiple accounts. The account creation process is limited to username and password combinations.
 
+:::tip
+Logto OSS (self-hosted) does not support configuring multiple administrators. For team collaboration and projects requiring multiple admin users, we recommend using [Logto Cloud](https://cloud.logto.io), which provides full team management features.
+:::
+
 ## Related resources \{#related-resources}
 
 <Url href="https://blog.logto.io/local-https">Dealing with local HTTPS development</Url>
diff --git a/docs/secret-vault/federated-token-set.mdx b/docs/secret-vault/federated-token-set.mdx
@@ -101,7 +101,7 @@ Once token storage is enabled and tokens are securely stored in Logto’s secret
 - `GET /my-account/sso-identities/:connectorId/access-token`: Retrieve the access token for an enterprise SSO identity by specifying the connector ID.
 
 :::info
-Learn how to [enable](/end-user-flows/account-settings/by-account-api#how-to-enable-account-api) and [access](/end-user-flows/account-settings/by-account-api#access-account-api-using-access-token) the Account API using the Logto issued access token.
+To retrieve third-party access tokens, you must first enable the Account API for end users at <CloudLink to="/sign-in-experience/account-center">Console > Sign-in & Account > Account center</CloudLink>. Learn how to [enable the Account API](/end-user-flows/account-settings/by-account-api#how-to-enable-account-api) and [access it using a Logto-issued access token](/end-user-flows/account-settings/by-account-api#access-account-api-using-access-token).
 :::
 
 ### Token rotation \{#token-rotation}
diff --git a/docs/user-management/manage-users.mdx b/docs/user-management/manage-users.mdx
@@ -43,10 +43,17 @@ To view the details of a user, simply click on the corresponding row in the user
   - **Phone number** ([primary_phone](/user-management/user-data#primary_phone)): Editable
   - **Username** ([username](/user-management/user-data#username)): Editable
   - **Password** ([has_password](/user-management/user-data#has_password)): You can regenerate a random password. Learn more about "[Reset user password](#reset-user-password)".
-  - **Social connections** ([identities](/user-management/user-data#social-identities)): View linked social accounts and social IDs. For example, if the user has signed in using their Facebook account, you will see a "Facebook" item in the list. You can remove a linked social identity in the Console. But you cannot link a new one on behalf of the end user.
-  - **Enterprise SSO connections** ([sso_identities](/user-management/user-data#sso-identities)): View linked enterprise identities. You cannot add or remove SSO identities in the Console.
   - **Multi-factor authentication** ([mfa_verification_factor](/user-management/user-data#mfa_verification_factors)): View all authentication factors (e.g., passkeys, authenticator apps, backup codes) this user has set up. Factors can be removed in the Console.
   - **Personal access token**: Create, view, rename, and delete [personal access tokens](/user-management/personal-access-token).
+- **Connection**:
+  - **Social connections** ([identities](/user-management/user-data#social-identities)):
+    - View the user's linked social accounts, including social IDs and profile details synced from their social providers (e.g., a "Facebook" entry will appear if the user signed in via Facebook).
+    - You can remove existing social identities, but you cannot link new social accounts on behalf of the user.
+    - For social connectors with [token storage](/secret-vault/federated-token-set) enabled, you can view and manage access tokens and refresh tokens in the connection detail page.
+  - **Enterprise SSO connections** ([sso_identities](/user-management/user-data#sso-identities)):
+    - View the user's linked enterprise identities, including enterprise IDs and profile details synced from their enterprise identity providers.
+    - You cannot add or remove enterprise SSO identities in the Console.
+    - For OIDC-based enterprise connectors with [token storage](/secret-vault/federated-token-set) enabled, you can view and delete tokens in the connection detail page.
 - **User profile data**: name, avatar URL, custom data, and additional OpenID Connect standard claims that are not included. All these profile fields are editable.
 
 :::warning
diff --git a/docs/user-management/user-data.mdx b/docs/user-management/user-data.mdx
@@ -70,12 +70,16 @@ _primary_email_ is the user's email address, used for sign-in with the email and
 
 Its value is usually from the email address that the user first registered with. It may be `null`. Its max length is 128.
 
+Only verified email addresses from social or enterprise SSO identity providers can be synced and saved as the `primary_email`.
+
 ### primary_phone \{#primary_phone}
 
 _primary_phone_ is the user's phone number, used for sign-in with the phone number and password / verification code from SMS.
 
 Its value is usually from the phone number that the user first registered with. It may be `null`. Its non-null value should contain numbers prefixed with the [country calling code](https://en.wikipedia.org/wiki/List_of_country_calling_codes) (excluding the plus sign `+`).
 
+Only verified phone numbers from social or enterprise SSO identity providers can be synced and saved as the `primary_phone`.
+
 ### name \{#name}
 
 _name_ is the user's full name. Its max length is 128.
