refactor: update account api docs (#1218)

* refactor: update account api docs

Update Account API and custom domain docs

* chore: update

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* chore: update

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* chore: update user data structure

Add Collect user profile and Account API information into "User data structure > Custom data" docs

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: Rany

docs/end-user-flows/account-settings/by-account-api.mdx

@@ -108,6 +108,8 @@ curl https://[tenant-id].logto.app/api/my-account \
 
 ### Retrieve user account information \{#retrieve-user-account-information}
 
+To get user data, you can use the [`GET /api/my-account`](https://openapi.logto.io/operation/operation-getprofile) endpoint.
+
 ```bash
 curl https://[tenant-id].logto.app/api/my-account \
   -H 'authorization: Bearer <access_token>'
@@ -128,9 +130,9 @@ The response fields may vary depending on the account center settings.
 
 ### Update basic account information \{#update-basic-account-information}
 
-Basic account information includes the username, name, avatar, and profile.
+Basic account information includes the username, name, avatar, custom data, and other profile information.
 
-To update username, name, and avatar, you can use the `PATCH /api/my-account` endpoint.
+To update **username, name, avatar, and customData** you can use the [`PATCH /api/my-account`](https://openapi.logto.io/operation/operation-updateprofile) endpoint.
 
 ```bash
 curl -X PATCH https://[tenant-id].logto.app/api/my-account \
@@ -139,7 +141,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account \
   --data-raw '{"username":"...","name":"...","avatar":"..."}'
 ```
 
-To update profile, you can use the `PATCH /api/my-account/profile` endpoint.
+To update other profile information, including **familyName, givenName, middleName, nickname, profile (profile page URL), website, gender, birthdate, zoneinfo, locale, and address**, you can use the [`PATCH /api/my-account/profile`](https://openapi.logto.io/operation/operation-updateotherprofile) endpoint.
 
 ```bash
 curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \
@@ -154,11 +156,9 @@ For security reasons, the Account API requires an additional layer of authorizat
 
 ### Get a verification record id \{#get-a-verification-record-id}
 
-First, you need to get a verification record ID. This can be used to verify the user's identity when updating identifiers.
-
-To get a verification record ID, you can verify the user's password or send a verification code to the user's email or phone.
+First, you need to get a **verification record ID** with a 10-minute expiration (TTL). This can be used to verify the user's identity before updating sensitive information. This means once a user successfully verifies their identity via password, email verification code, or SMS verification code, they have 10 minutes to update their authentication-related data, including identifiers, credentials, social account linking, and MFA.
 
-To learn more about verifications, please refer to [Security verification by Account API](/end-user-flows/security-verification).
+To get a verification record ID, you can [verify the user's password](#verify-the-users-password) or [send a verification code to the user's email or phone](#verify-by-sending-a-verification-code-to-the-users-email-or-phone).
 
 #### Verify the user's password \{#verify-the-users-password}
 
@@ -213,13 +213,15 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v
 
 After verifying the code, you can now use the verification record ID to update the user's identifier.
 
+To learn more about verifications, please refer to [Security verification by Account API](/end-user-flows/security-verification).
+
 ### Send request with verification record id \{#send-request-with-verification-record-id}
 
 When sending a request to update the user's identifier, you need to include the verification record ID in the request header with the `logto-verification-id` field.
 
 ### Update user's password \{#update-users-password}
 
-To update the user's password, you can use the `POST /api/my-account/password` endpoint.
+To update the user's password, you can use the [`POST /api/my-account/password`](https://openapi.logto.io/operation/operation-updatepassword) endpoint.
 
 ```bash
 curl -X POST https://[tenant-id].logto.app/api/my-account/password \
@@ -237,7 +239,7 @@ To use this method, you need to [configure the email connector](/connectors/emai
 
 To update or link a new email, you should first prove the ownership of the email.
 
-Call the `POST /api/verifications/verification-code` endpoint to request a verification code.
+Call the [`POST /api/verifications/verification-code`](https://openapi.logto.io/operation/operation-createverificationbyverificationcode) endpoint to request a verification code.
 
 ```bash
 curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
@@ -255,7 +257,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v
   --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}'
 ```
 
-After verifying the code, you can now update the user's email, set the `verificationId` to the request body as `newIdentifierVerificationRecordId`.
+After verifying the code, you can now call [`PATCH /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-updateprimaryemail) to update the user's email, set the `verificationId` to the request body as `newIdentifierVerificationRecordId`.
 
 ```bash
 curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
@@ -267,7 +269,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
 
 ### 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` endpoint.
+To remove the user's email, you can use the [`DELETE /api/my-account/primary-email`](https://openapi.logto.io/operation/operation-deleteprimaryemail) endpoint.
 
 ```bash
 curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \
@@ -281,11 +283,11 @@ curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \
 To use this method, you need to [configure the SMS connector](/connectors/sms-connectors/), and make sure the `BindNewIdentifier` template is configured.
 :::
 
-Similar to updating email, you can use the `PATCH /api/my-account/primary-phone` endpoint to update or link a new phone. And use the `DELETE /api/my-account/primary-phone` endpoint to remove the user's phone.
+Similar to updating email, you can use the [`PATCH /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-updateprimaryphone) endpoint to update or link a new phone. And use the [`DELETE /api/my-account/primary-phone`](https://openapi.logto.io/operation/operation-deleteprimaryphone) endpoint to remove the user's phone.
 
 ### Link a new social connection \{#link-a-new-social-connection}
 
-To link a new social connection, first you should request an authorization URL:
+To link a new social connection, first you should request an authorization URL with [`POST /api/verifications/social`](https://openapi.logto.io/operation/operation-createverificationbysocial).
 
 ```bash
 curl -X POST https://[tenant-id].logto.app/api/verifications/social \
@@ -300,7 +302,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social \
 
 In the response, you will find a `verificationRecordId`, keep it for later use.
 
-After the user authorizes the application, you will receive a callback at the `redirectUri` with the `state` parameter. Then you can use the `POST /api/verifications/social/verify` endpoint to verify the social connection.
+After the user authorizes the application, you will receive a callback at the `redirectUri` with the `state` parameter. Then you can use the [`POST /api/verifications/social/verify`](https://openapi.logto.io/operation/operation-verifyverificationbysocial) endpoint to verify the social connection.
 
 ```bash
 curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \
@@ -311,7 +313,7 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \
 
 The `connectorData` is the data returned by the social connector after the user authorizes the application, you need to parse and get the query parameters from the `redirectUri` in your callback page, and wrap them as a JSON as the value of the `connectorData` field.
 
-Finally, you can use the `POST /api/my-account/identities` endpoint to link the social connection.
+Finally, you can use the [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) endpoint to link the social connection.
 
 ```bash
 curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
@@ -323,7 +325,7 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
 
 ### Remove a social connection \{#remove-a-social-connection}
 
-To remove a social connection, you can use the `DELETE /api/my-account/identities` endpoint.
+To remove a social connection, you can use the [`DELETE /api/my-account/identities`](https://openapi.logto.io/operation/operation-deleteidentity) endpoint.
 
 ```bash
 curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \
@@ -338,27 +340,36 @@ Remember to [enable MFA and WebAuthn](/end-user-flows/mfa) first.
 :::
 
 :::note
-To use this method, you need to enable the `mfa` field in the account center settings.
+To use this method, you need to enable the `mfa` field in the [account center settings](#how-to-enable-account-api).
 :::
 
-**Step 0: Add your front-end app origin to the related origins.**
+**Step 1: Add your front-end app origin to the related origins**
 
-A passkey in Browser is linked to a specific hostname (RP ID), and only the origin of the RP ID can be used to register or verify a passkey. However, your front-end app which is sending the request to the Account API is not the same as Logto's sign-in page, so you need to add your front-end app origin to the related origins list. This will allow your front-end app to register and verify a passkey under other RP IDs.
+WebAuthn passkeys are bound to a specific hostname called the **Relying Party ID (RP ID)**. Only applications hosted on the RP ID's origin can register or authenticate with those passkeys.
 
-By default, Logto will set the RP ID to the tenant domain, for example, if your tenant domain is `https://example.logto.app`, the RP ID will be `example.logto.app`. If you are using a custom domain, the RP ID will be the custom domain, for example, if your custom domain is `https://auth.example.com`, the RP ID will be `auth.example.com`.
+Since your front-end application calls the Account API from a different domain than Logto's authentication pages, you need to configure **Related Origins** to allow cross-origin passkey operations.
 
-Now, let's add your front-end app origin to the related origins, for example, if your front-end app origin is `https://account.example.com`:
+**How Logto determines the RP ID:**
+
+- **Default setup**: If you only use Logto's default domain `https://[tenant-id].logto.app`, the RP ID is `[tenant-id].logto.app`
+- **Custom domain**: If you've configured a [custom domain](/logto-cloud/custom-domain) like `https://auth.example.com`, the RP ID becomes `auth.example.com`
+
+**Configure Related Origins:**
+
+Use the [`PATCH /api/account-center`](https://openapi.logto.io/operation/operation-updateaccountcentersettings) endpoint to add your front-end application's origin. For example, if your app's account center runs on `https://account.example.com`:
 
 ```bash
-curl -X PATCH https://[tenant-id].logto.app/api/webauthn-connectors \
+curl -X PATCH https://[tenant-id].logto.app/api/account-center \
   -H 'authorization: Bearer <access_token>' \
   -H 'content-type: application/json' \
   --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.
 
-**Step 1: request new registration options.**
+**Step 2: Request new registration options**
+
+Use the [`POST /api/verifications/web-authn/registration`](https://openapi.logto.io/operation/operation-generatewebauthnregistrationoptions) endpoint to request registration for a new passkey. Logto allows each user account to register multiple passkeys.
 
 ```bash
 curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \
@@ -376,7 +387,7 @@ You'll get a response like:
 }
 ```
 
-**Step 2: register the passkey in local browser.**
+**Step 3: Register the passkey in local browser**
 
 Take [`@simplewebauthn/browser`](https://simplewebauthn.dev/) as an example, you can use the `startRegistration` function to register the passkey in local browser.
 
@@ -390,7 +401,11 @@ const response = await startRegistration({
 // Save the response for later use
 ```
 
-**Step 3: verify the passkey.**
+**Step 4: Verify the passkey registration**
+
+Use the [`POST /api/verifications/web-authn/registration/verify`](https://openapi.logto.io/operation/operation-verifywebauthnregistration) endpoint to verify the passkey registration.
+
+This step verifies the cryptographic signature generated by the authenticator to ensure the passkey was legitimately created and hasn't been tampered with during transmission.
 
 ```bash
 curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \
@@ -402,7 +417,9 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registrat
 - `payload`: The response from the local browser in step 2.
 - `verificationRecordId`: The verification record ID returned by the server in step 1.
 
-**Step 4: finally, you can link the passkey.**
+**Step 5: Link the passkey**
+
+Finally, you can link the passkey to the user's account using the [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) endpoint.
 
 ```bash
 curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
@@ -416,9 +433,9 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
 - `type`: the type of the MFA factor, currently only `WebAuthn` is supported.
 - `newIdentifierVerificationRecordId`: the verification record ID returned by the server in step 1.
 
-### Manage existing WebAuthn passkey \{#manage-existing-webauthn-passkey}
+### Manage existing WebAuthn passkeys \{#manage-existing-webauthn-passkeys}
 
-To manage an existing WebAuthn passkey, you can use the `GET /api/my-account/mfa-verifications` endpoint to get current passkeys and other MFA verification factors.
+To manage existing WebAuthn passkeys, you can use the [`GET /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-getmfaverifications) endpoint to get current passkeys and other MFA verification factors.
 
 ```bash
 curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \
@@ -445,7 +462,7 @@ The response body would be like:
 - `name`: the name of the passkey, optional field.
 - `agent`: the user agent of the passkey.
 
-Update the passkey name:
+Update the passkey name using [`PATCH /api/my-account/mfa-verifications/{verificationId}/name`](https://openapi.logto.io/operation/operation-updatemfaverificationname) endpoint:
 
 ```bash
 curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \
@@ -455,7 +472,7 @@ curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{ve
   --data-raw '{"name":"..."}'
 ```
 
-Delete the passkey:
+Delete the passkey using [`DELETE /api/my-account/mfa-verifications/{verificationId}`](https://openapi.logto.io/operation/operation-deletemfaverification) endpoint:
 
 ```bash
 curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \
@@ -470,10 +487,12 @@ Remember to [enable MFA and TOTP](/end-user-flows/mfa) first.
 :::
 
 :::note
-To use this method, you need to enable the `mfa` field in the account center settings.
+To use this method, you need to enable the `mfa` field in the [account center settings](#how-to-enable-account-api).
 :::
 
-**Step 1: Generate a TOTP secret.**
+**Step 1: Generate a TOTP secret**
+
+Use the [`POST /api/my-account/mfa-verifications/totp-secret/generate`](https://openapi.logto.io/operation/operation-generatetotpsecret) endpoint to generate a TOTP secret.
 
 ```bash
 curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \
@@ -489,7 +508,7 @@ The response body would be like:
 }
 ```
 
-**Step 2: Display the TOTP secret to the user.**
+**Step 2: Display the TOTP secret to the user**
 
 Use the secret to generate a QR code or display it directly to the user. The user should add it to their authenticator app (such as Google Authenticator, Microsoft Authenticator, or Authy).
 
@@ -505,9 +524,9 @@ Example:
 otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp
 ```
 
-**Step 3: Bind the TOTP factor.**
+**Step 3: Bind the TOTP factor**
 
-After the user has added the secret to their authenticator app, they need to verify it and bind it to their account:
+After the user has added the secret to their authenticator app, they need to verify it and bind it to their account. Use the [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) endpoint to bind the TOTP factor.
 
 ```bash
 curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
@@ -532,10 +551,12 @@ Remember to [enable MFA and backup codes](/end-user-flows/mfa) first.
 :::
 
 :::note
-To use this method, you need to enable the `mfa` field in the account center settings.
+To use this method, you need to enable the `mfa` field in the [account center settings](#how-to-enable-account-api).
 :::
 
-**Step 1: Generate new backup codes:**
+**Step 1: Generate new backup codes**
+
+Use the [`POST /api/my-account/mfa-verifications/backup-codes/generate`](https://openapi.logto.io/operation/operation-generatemyaccountbackupcodes) endpoint to generate a new set of 10 backup codes.
 
 ```bash
 curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \
@@ -551,9 +572,8 @@ The response body would be like:
 }
 ```
 
-**Step 2: Display backup codes to the user:**
+**Step 2: Display backup codes to the user**
 
-:::important
 Before binding the backup codes to the user's account, you must display them to the user and instruct them to:
 
 - Download or write down these codes immediately
@@ -562,9 +582,10 @@ Before binding the backup codes to the user's account, you must display them to
 - Know that these codes are their last resort if they lose access to their primary MFA methods
 
 You should display the codes in a clear, easy-to-copy format and consider providing a download option (e.g., as a text file or PDF).
-:::
 
-**Step 3: Bind backup codes to the user account:**
+**Step 3: Bind backup codes to the user account**
+
+Use the [`POST /api/my-account/mfa-verifications`](https://openapi.logto.io/operation/operation-addmfaverification) endpoint to bind the backup codes to the user's account.
 
 ```bash
 curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
@@ -586,7 +607,9 @@ curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
 
 :::
 
-**View existing backup codes:**
+**View existing backup codes**
+
+To view existing backup codes and their usage status, use the [`GET /api/my-account/mfa-verifications/backup-codes`](https://openapi.logto.io/operation/operation-getbackupcodes) endpoint:
 
 ```bash
 curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \

docs/logto-cloud/custom-domain.mdx

@@ -72,8 +72,6 @@ Once you've configured your settings, both your custom domain name and the defau
 
 In this article, we assume that your custom domain is `auth.example.com`.
 
-<img src="/img/assets/custom-domain-added.jpeg" alt="Custom domain added" />
-
 :::
 
 ### Updating the SDK endpoint for applications \{#updating-the-sdk-endpoint-for-applications}