docs: clarify two different verification record IDs in Account API (#1338)

Add info boxes and code comments to distinguish between:
- logto-verification-id (header): proves user identity
- newIdentifierVerificationRecordId (body): proves ownership of new identifier

This helps users understand which verification ID to use where when
linking email, phone, or social connections.

Author: wangsijie

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

@@ -251,12 +251,23 @@ curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/v
 
 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`.
 
+:::info[Two different verification record IDs]
+
+This request requires two separate verification record IDs:
+
+- **`logto-verification-id` (header)**: Proves the user's identity before making sensitive changes. Obtain this by [verifying the user's password](#verify-the-users-password) or [sending a verification code to the user's existing email or phone](#verify-by-sending-a-verification-code-to-the-users-email-or-phone).
+- **`newIdentifierVerificationRecordId` (body)**: Proves ownership of the new email address. This is the `verificationRecordId` returned from the `POST /api/verifications/verification-code` call above.
+
+:::
+
 ```bash
 curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
   -H 'authorization: Bearer <access_token>' \
-  -H 'logto-verification-id: <verification_record_id>' \
+  # Verifies user identity (from password or existing email/phone verification)
+  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
   -H 'content-type: application/json' \
-  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}'
+  # The "newIdentifierVerificationRecordId" proves ownership of the new email (from the verification code flow above)
+  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'
 ```
 
 :::tip
@@ -311,12 +322,23 @@ The `connectorData` is the data returned by the social connector after the user
 
 Finally, you can use the [`POST /api/my-account/identities`](https://openapi.logto.io/operation/operation-adduseridentities) endpoint to link the social connection.
 
+:::info[Two different verification record IDs]
+
+This request requires two separate verification record IDs:
+
+- **`logto-verification-id` (header)**: Proves the user's identity before making sensitive changes. Obtain this by [verifying the user's password](#verify-the-users-password) or [sending a verification code to the user's existing email or phone](#verify-by-sending-a-verification-code-to-the-users-email-or-phone).
+- **`newIdentifierVerificationRecordId` (body)**: Identifies the social identity being linked. This is the `verificationRecordId` returned from the `POST /api/verifications/social` call above.
+
+:::
+
 ```bash
 curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
   -H 'authorization: Bearer <access_token>' \
-  -H 'logto-verification-id: <verification_record_id>' \
+  # Verifies user identity (from password or existing email/phone verification)
+  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
   -H 'content-type: application/json' \
-  --data-raw '{"newIdentifierVerificationRecordId":"..."}'
+  # The "newIdentifierVerificationRecordId" identifies the social connection to link (from the social verification flow above)
+  --data-raw '{"newIdentifierVerificationRecordId":"<verification_record_id_from_social>"}'
 ```
 
 ### Remove a social connection \{#remove-a-social-connection}