การตั้งค่าบัญชีผู้ใช้ด้วย Account API

Logto Account API คืออะไร

Logto Account API คือชุด API ที่ครอบคลุมซึ่งเปิดให้ผู้ใช้ปลายทางเข้าถึง API ได้โดยตรงโดยไม่ต้องผ่าน Management API จุดเด่นมีดังนี้:

เข้าถึงโดยตรง: Account API ให้อำนาจผู้ใช้ปลายทางในการเข้าถึงและจัดการโปรไฟล์บัญชีของตนเองโดยตรง โดยไม่ต้องส่งต่อผ่าน Management API
การจัดการโปรไฟล์ผู้ใช้และอัตลักษณ์: ผู้ใช้สามารถจัดการโปรไฟล์และการตั้งค่าความปลอดภัยได้อย่างเต็มที่ รวมถึงการอัปเดตข้อมูลอัตลักษณ์ เช่น อีเมล โทรศัพท์ รหัสผ่าน และการเชื่อมต่อโซเชียล รองรับ MFA และ SSO กำลังจะมาเร็ว ๆ นี้
การควบคุมการเข้าถึงระดับโลก: ผู้ดูแลระบบมีสิทธิ์ควบคุมการเข้าถึงแบบเต็มรูปแบบและสามารถปรับแต่งแต่ละฟิลด์ได้
การอนุญาต (Authorization) ที่ไร้รอยต่อ: การอนุญาต (Authorization) ง่ายกว่าที่เคย! เพียงใช้ client.getAccessToken() เพื่อรับโทเค็นการเข้าถึงทึบ (opaque access token) สำหรับ OP (Logto) และแนบไปกับ Authorization header เป็น Bearer <access_token>

ด้วย Logto Account API คุณสามารถสร้างระบบจัดการบัญชีผู้ใช้แบบกำหนดเอง เช่น หน้าโปรไฟล์ ที่ผสานรวมกับ Logto ได้อย่างสมบูรณ์

ตัวอย่างการใช้งานที่พบบ่อย ได้แก่:

ดึงข้อมูลโปรไฟล์ผู้ใช้
อัปเดตโปรไฟล์ผู้ใช้
อัปเดตรหัสผ่านผู้ใช้
อัปเดตอัตลักษณ์ผู้ใช้ เช่น อีเมล โทรศัพท์ และการเชื่อมต่อโซเชียล
จัดการปัจจัย MFA (การยืนยันตัวตนหลายปัจจัย)

หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับ API ที่มีอยู่ โปรดดูที่ Logto Account API Reference และ Logto Verification API Reference

บันทึก:

ฟีเจอร์การดูบัญชี SSO และการลบบัญชี มีให้ใช้งานผ่าน Logto Management APIs เท่านั้น ดูรายละเอียดการใช้งานได้ที่ การตั้งค่าบัญชีผู้ใช้ด้วย Management API

วิธีเปิดใช้งาน Account API

ไปที่ Console > Sign-in & account > Account center

Account API ถูกปิดใช้งานโดยค่าเริ่มต้น ดังนั้นการควบคุมการเข้าถึงจะถูกล็อกไว้ ให้สลับเปิด Enable Account API เพื่อเปิดใช้งาน

เมื่อเปิดใช้งานแล้ว ให้กำหนดสิทธิ์แต่ละฟิลด์สำหรับ identifier, ข้อมูลโปรไฟล์ และการเข้าถึงโทเค็นของบุคคลที่สาม แต่ละฟิลด์รองรับ Off, ReadOnly หรือ Edit โดยค่าเริ่มต้นคือ Off

ฟิลด์ความปลอดภัย:
- ฟิลด์ประกอบด้วย: อีเมลหลัก, โทรศัพท์หลัก, อัตลักษณ์โซเชียล, รหัสผ่าน และ MFA
- ก่อนที่ผู้ใช้ปลายทางจะสามารถแก้ไขฟิลด์เหล่านี้ได้ ต้องยืนยันตัวตนผ่านรหัสผ่าน อีเมล หรือ SMS เพื่อรับรหัสบันทึกการยืนยัน (verification record ID) ที่มีอายุ 10 นาที ดู รับรหัสบันทึกการยืนยัน
- หากต้องการใช้ WebAuthn passkey สำหรับ MFA ให้เพิ่มโดเมนแอป front-end ของคุณใน WebAuthn Related Origins เพื่อให้ account center และประสบการณ์การลงชื่อเข้าใช้สามารถใช้ passkey ร่วมกันได้ ดู เชื่อมโยง WebAuthn passkey ใหม่
ฟิลด์โปรไฟล์:
- ฟิลด์ประกอบด้วย: ชื่อผู้ใช้, ชื่อ, อวาตาร์, profile (แอตทริบิวต์โปรไฟล์มาตรฐานอื่น ๆ) และ custom data
- ผู้ใช้ปลายทางสามารถแก้ไขฟิลด์เหล่านี้ได้โดยไม่ต้องยืนยันตัวตนเพิ่มเติม
Secret vault: สำหรับ OIDC หรือ OAuth social และ enterprise connectors, Logto secret vault จะเก็บโทเค็นการเข้าถึงและรีเฟรชของบุคคลที่สามอย่างปลอดภัยหลังการยืนยันตัวตน แอปสามารถเรียก API ภายนอก เช่น ซิงค์กิจกรรม Google Calendar ได้โดยไม่ต้องให้ผู้ใช้ลงชื่อเข้าใช้อีก การดึงโทเค็นจะพร้อมใช้งานโดยอัตโนมัติเมื่อเปิด Account API

วิธีเข้าถึง Account API

บันทึก:

เพื่อให้แน่ใจว่า access token มีสิทธิ์ที่เหมาะสม โปรดกำหนดค่า scopes ที่เกี่ยวข้องใน Logto config ของคุณให้ถูกต้อง

ตัวอย่างเช่น สำหรับ API POST /api/my-account/primary-email คุณต้องกำหนดค่า scope email สำหรับ API POST /api/my-account/primary-phone คุณต้องกำหนดค่า scope phone

import { type LogtoConfig, UserScope } from '@logto/js';

const config: LogtoConfig = {
  // ...ตัวเลือกอื่น ๆ
  // เพิ่ม scopes ที่เหมาะสมกับกรณีการใช้งานของคุณ
  scopes: [
    UserScope.Email, // สำหรับ `{POST,DELETE} /api/my-account/primary-email`
    UserScope.Phone, // สำหรับ `{POST,DELETE} /api/my-account/primary-phone`
    UserScope.CustomData, // จัดการ custom data
    UserScope.Address, // จัดการ address
    UserScope.Identities, // สำหรับ API ที่เกี่ยวข้องกับอัตลักษณ์และ MFA
    UserScope.Profile, // จัดการโปรไฟล์ผู้ใช้
  ],
};

ดึง access token

หลังจากตั้งค่า SDK ในแอปของคุณแล้ว คุณสามารถใช้เมธอด client.getAccessToken() เพื่อดึง access token ได้ โทเค็นนี้เป็นโทเค็นทึบ (opaque token) ที่ใช้เข้าถึง Account API

หากคุณไม่ได้ใช้ SDK อย่างเป็นทางการ ให้ตั้งค่า resource เป็นค่าว่างสำหรับ access token grant request ไปที่ /oidc/token

เข้าถึง Account API ด้วย access token

คุณควรแนบ access token ในฟิลด์ Authorization ของ HTTP headers ในรูปแบบ Bearer (Bearer YOUR_TOKEN) เมื่อเรียกใช้งาน Account API

ตัวอย่างการดึงข้อมูลบัญชีผู้ใช้:

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

จัดการข้อมูลบัญชีผู้ใช้พื้นฐาน

ดึงข้อมูลบัญชีผู้ใช้

เพื่อดึงข้อมูลผู้ใช้ คุณสามารถใช้ endpoint GET /api/my-account

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

ตัวอย่าง response:

{
  "id": "...",
  "username": "...",
  "name": "...",
  "avatar": "..."
}

ฟิลด์ใน response อาจแตกต่างกันไปตามการตั้งค่า account center

อัปเดตข้อมูลบัญชีผู้ใช้พื้นฐาน

ข้อมูลบัญชีผู้ใช้พื้นฐานประกอบด้วย ชื่อผู้ใช้, ชื่อ, อวาตาร์, custom data และข้อมูลโปรไฟล์อื่น ๆ

เพื่ออัปเดต username, name, avatar, และ customData ให้ใช้ endpoint PATCH /api/my-account

curl -X PATCH https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"username":"...","name":"...","avatar":"..."}'

เพื่ออัปเดตข้อมูลโปรไฟล์อื่น ๆ เช่น familyName, givenName, middleName, nickname, profile (URL หน้าโปรไฟล์), website, gender, birthdate, zoneinfo, locale, และ address ให้ใช้ endpoint PATCH /api/my-account/profile

curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"familyName":"...","givenName":"..."}'

จัดการ identifier และข้อมูลสำคัญอื่น ๆ

ด้วยเหตุผลด้านความปลอดภัย Account API ต้องการการอนุญาต (Authorization) เพิ่มเติมสำหรับการดำเนินการที่เกี่ยวข้องกับ identifier และข้อมูลสำคัญอื่น ๆ

รับรหัสบันทึกการยืนยัน (verification record id)

ก่อนอื่น คุณต้องขอ verification record ID ที่มีอายุ 10 นาที (TTL) เพื่อใช้ยืนยันตัวตนผู้ใช้ก่อนอัปเดตข้อมูลสำคัญ หมายความว่าเมื่อผู้ใช้ยืนยันตัวตนสำเร็จผ่านรหัสผ่าน, โค้ดยืนยันอีเมล หรือโค้ดยืนยัน SMS แล้ว จะมีเวลา 10 นาทีในการอัปเดตข้อมูลที่เกี่ยวข้องกับการยืนยันตัวตน เช่น identifier, ข้อมูลรับรอง, การเชื่อมต่อบัญชีโซเชียล และ MFA

เพื่อขอ verification record ID คุณสามารถ ยืนยันรหัสผ่านผู้ใช้ หรือ ส่งโค้ดยืนยันไปยังอีเมลหรือโทรศัพท์ของผู้ใช้

ยืนยันรหัสผ่านผู้ใช้

curl -X POST https://[tenant-id].logto.app/api/verifications/password \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'

ตัวอย่าง response:

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

ยืนยันโดยส่งโค้ดยืนยันไปยังอีเมลหรือโทรศัพท์ของผู้ใช้

บันทึก:

เพื่อใช้วิธีนี้ คุณต้อง ตั้งค่าตัวเชื่อมต่ออีเมล หรือ ตัวเชื่อมต่อ SMS และตรวจสอบให้แน่ใจว่าได้ตั้งค่าเทมเพลต UserPermissionValidation แล้ว

ตัวอย่างการขอโค้ดยืนยันใหม่และรับ verification record ID (กรณีอีเมล):

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

ตัวอย่าง response:

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

เมื่อได้รับโค้ดยืนยันแล้ว คุณสามารถใช้โค้ดนี้เพื่ออัปเดตสถานะการยืนยันของ verification record

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}'

หลังจากยืนยันโค้ดแล้ว คุณสามารถใช้ verification record ID เพื่ออัปเดต identifier ของผู้ใช้ได้

หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับการยืนยัน โปรดดู Security verification by Account API

ส่งคำขอพร้อม verification record id

เมื่อส่งคำขอเพื่ออัปเดต identifier ของผู้ใช้ คุณต้องแนบ verification record ID ใน request header ด้วยฟิลด์ logto-verification-id

อัปเดตรหัสผ่านผู้ใช้

เพื่ออัปเดตรหัสผ่านผู้ใช้ ให้ใช้ endpoint POST /api/my-account/password

curl -X POST https://[tenant-id].logto.app/api/my-account/password \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'

เคล็ดลับ:

เช่นเดียวกับรหัสผ่านที่สร้างระหว่างการสมัคร รหัสผ่านที่ตั้งผ่าน Account API ต้องเป็นไปตาม นโยบายรหัสผ่าน ที่คุณตั้งค่าไว้ใน Console > Security > Password policy Logto จะส่งผลการตรวจสอบและข้อความผิดพลาดโดยละเอียดหากรหัสผ่านไม่ผ่านนโยบาย

อัปเดตหรือเชื่อมโยงอีเมลใหม่

บันทึก:

เพื่อใช้วิธีนี้ คุณต้อง ตั้งค่าตัวเชื่อมต่ออีเมล และตรวจสอบให้แน่ใจว่าได้ตั้งค่าเทมเพลต BindNewIdentifier แล้ว

เพื่ออัปเดตหรือเชื่อมโยงอีเมลใหม่ คุณต้องพิสูจน์ความเป็นเจ้าของอีเมลนั้นก่อน

เรียก endpoint POST /api/verifications/verification-code เพื่อขอโค้ดยืนยัน

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

คุณจะพบ verificationId ใน response และได้รับโค้ดยืนยันทางอีเมล ให้นำไปยืนยันอีเมล

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}'

หลังจากยืนยันโค้ดแล้ว ให้เรียก PATCH /api/my-account/primary-email เพื่ออัปเดตอีเมลของผู้ใช้ โดยใส่ verificationId ใน request body เป็น newIdentifierVerificationRecordId

ต้องใช้ verification record ID สองชุด:

คำขอนี้ต้องใช้ verification record ID สองชุดแยกกัน:

logto-verification-id (header): พิสูจน์ตัวตนผู้ใช้ก่อนเปลี่ยนแปลงข้อมูลสำคัญ รับได้โดย ยืนยันรหัสผ่านผู้ใช้ หรือ ส่งโค้ดยืนยันไปยังอีเมลหรือโทรศัพท์เดิมของผู้ใช้
newIdentifierVerificationRecordId (body): พิสูจน์ความเป็นเจ้าของอีเมลใหม่ คือ verificationRecordId ที่ได้จาก POST /api/verifications/verification-code ข้างต้น

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_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # "newIdentifierVerificationRecordId" พิสูจน์ความเป็นเจ้าของอีเมลใหม่ (จาก flow ยืนยันโค้ดข้างต้น)
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'

เคล็ดลับ:

เช่นเดียวกับอีเมลที่เก็บระหว่างการสมัคร อีเมลใด ๆ ที่เชื่อมโยงผ่าน Account API ต้องผ่านการตรวจสอบ blocklist ที่คุณตั้งค่าไว้ใน Console > Security > Blocklist Logto จะปฏิเสธคำขอและส่งข้อความผิดพลาดโดยละเอียดหากอีเมลละเมิดนโยบาย

ลบอีเมลของผู้ใช้

เพื่อลบอีเมลของผู้ใช้ ให้ใช้ endpoint DELETE /api/my-account/primary-email

curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

จัดการโทรศัพท์

บันทึก:

เพื่อใช้วิธีนี้ คุณต้อง ตั้งค่าตัวเชื่อมต่อ SMS และตรวจสอบให้แน่ใจว่าได้ตั้งค่าเทมเพลต BindNewIdentifier แล้ว

เช่นเดียวกับการอัปเดตอีเมล คุณสามารถใช้ endpoint PATCH /api/my-account/primary-phone เพื่ออัปเดตหรือเชื่อมโยงโทรศัพท์ใหม่ และใช้ endpoint DELETE /api/my-account/primary-phone เพื่อลบโทรศัพท์ของผู้ใช้

เพื่อเชื่อมโยงบัญชีโซเชียลใหม่ ให้ขอ authorization URL ก่อนด้วย POST /api/verifications/social

curl -X POST https://[tenant-id].logto.app/api/verifications/social \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}'

connectorId: รหัสของ social connector
redirectUri: URI ที่จะเปลี่ยนเส้นทางหลังผู้ใช้อนุญาตแอป คุณควรโฮสต์เว็บเพจที่ URL นี้และจับ callback
state: สถานะที่จะส่งกลับหลังผู้ใช้อนุญาตแอป เป็นสตริงสุ่มเพื่อป้องกัน CSRF

ใน response คุณจะพบ verificationRecordId ให้เก็บไว้ใช้ในขั้นตอนถัดไป

หลังผู้ใช้อนุญาตแอป คุณจะได้รับ callback ที่ redirectUri พร้อมพารามิเตอร์ state จากนั้นใช้ endpoint POST /api/verifications/social/verify เพื่อยืนยันบัญชีโซเชียล

curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorData":"...","verificationRecordId":"..."}'

connectorData คือข้อมูลที่ได้จาก social connector หลังผู้ใช้อนุญาตแอป คุณต้องแยก query parameters จาก redirectUri ในหน้า callback ของคุณ และห่อเป็น JSON สำหรับฟิลด์ connectorData

สุดท้าย ใช้ endpoint POST /api/my-account/identities เพื่อเชื่อมโยงบัญชีโซเชียล

ต้องใช้ verification record ID สองชุด:

คำขอนี้ต้องใช้ verification record ID สองชุดแยกกัน:

logto-verification-id (header): พิสูจน์ตัวตนผู้ใช้ก่อนเปลี่ยนแปลงข้อมูลสำคัญ รับได้โดย ยืนยันรหัสผ่านผู้ใช้ หรือ ส่งโค้ดยืนยันไปยังอีเมลหรือโทรศัพท์เดิมของผู้ใช้
newIdentifierVerificationRecordId (body): ระบุอัตลักษณ์โซเชียลที่กำลังเชื่อมโยง คือ verificationRecordId ที่ได้จาก POST /api/verifications/social ข้างต้น

curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
  -H 'authorization: Bearer <access_token>' \
  # พิสูจน์ตัวตนผู้ใช้ (จากรหัสผ่านหรืออีเมล/โทรศัพท์เดิม)
  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # "newIdentifierVerificationRecordId" ระบุบัญชีโซเชียลที่จะเชื่อมโยง (จาก flow ยืนยันโซเชียลข้างต้น)
  --data-raw '{"newIdentifierVerificationRecordId":"<verification_record_id_from_social>"}'

เพื่อลบบัญชีโซเชียล ให้ใช้ endpoint DELETE /api/my-account/identities

curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

เชื่อมโยง WebAuthn passkey ใหม่

บันทึก:

อย่าลืม เปิดใช้งาน MFA และ WebAuthn ก่อน

บันทึก:

เพื่อใช้วิธีนี้ คุณต้องเปิดใช้งานฟิลด์ mfa ใน การตั้งค่า account center

ขั้นตอนที่ 1: เพิ่ม origin ของแอป front-end ของคุณใน Related Origins

WebAuthn passkey จะผูกกับ hostname เฉพาะที่เรียกว่า Relying Party ID (RP ID) เฉพาะแอปที่โฮสต์บน origin ของ RP ID เท่านั้นที่สามารถลงทะเบียนหรือยืนยันตัวตนด้วย passkey เหล่านั้นได้

เนื่องจากแอป front-end ของคุณเรียก Account API จากโดเมนที่ต่างจากหน้าการยืนยันตัวตนของ Logto คุณต้องกำหนดค่า Related Origins เพื่ออนุญาตการใช้งาน passkey ข้าม origin

Logto กำหนด RP ID อย่างไร:

ค่าเริ่มต้น: หากใช้โดเมน Logto เริ่มต้น https://[tenant-id].logto.app RP ID คือ [tenant-id].logto.app
Custom domain: หากตั้งค่า custom domain เช่น https://auth.example.com RP ID จะเป็น auth.example.com

กำหนดค่า Related Origins:

ใช้ endpoint PATCH /api/account-center เพื่อเพิ่ม origin ของแอป front-end ของคุณ เช่น ถ้า account center ของแอปรันที่ https://account.example.com:

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"]}'

บันทึก:

WebAuthn รองรับได้สูงสุด 5 label eTLD+1 สำหรับ Related Origins โดย eTLD+1 (effective top-level domain plus one label) คือส่วนโดเมนที่ลงทะเบียนได้ เช่น:

https://example.com, https://app.example.com, https://auth.example.com นับเป็น หนึ่ง label (example.com)
https://shopping.com, https://shopping.co.uk, https://shopping.co.jp ก็นับเป็น หนึ่ง label (shopping)
https://example.com และ https://another.com นับเป็น สอง label

หากต้องการรองรับมากกว่า 5 โดเมนสำหรับ Related Origins โปรดดู Related Origin Requests สำหรับรายละเอียด

ขั้นตอนที่ 2: ขอ registration options ใหม่

ใช้ endpoint POST /api/verifications/web-authn/registration เพื่อขอลงทะเบียน passkey ใหม่ Logto อนุญาตให้แต่ละบัญชีผู้ใช้ลงทะเบียน passkey ได้หลายอัน

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

ตัวอย่าง response:

{
  "registrationOptions": "...",
  "verificationRecordId": "...",
  "expiresAt": "..."
}

ขั้นตอนที่ 3: ลงทะเบียน passkey ในเบราว์เซอร์

ตัวอย่างใช้ @simplewebauthn/browser สามารถใช้ฟังก์ชัน startRegistration เพื่อลงทะเบียน passkey ในเบราว์เซอร์

import { startRegistration } from '@simplewebauthn/browser';

// ...
const response = await startRegistration({
  optionsJSON: registrationOptions, // ข้อมูลที่ได้จากเซิร์ฟเวอร์ในขั้นตอนที่ 1
});
// บันทึก response ไว้ใช้ในขั้นตอนถัดไป

ขั้นตอนที่ 4: ยืนยันการลงทะเบียน passkey

ใช้ endpoint POST /api/verifications/web-authn/registration/verify เพื่อยืนยันการลงทะเบียน passkey

ขั้นตอนนี้จะตรวจสอบลายเซ็นดิจิทัลที่สร้างโดย authenticator เพื่อให้แน่ใจว่า passkey ถูกสร้างขึ้นอย่างถูกต้องและไม่ถูกแก้ไขระหว่างส่งข้อมูล

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"payload":"...","verificationRecordId":"..."}'

payload: response จากเบราว์เซอร์ในขั้นตอนที่ 2
verificationRecordId: verification record ID ที่ได้จากเซิร์ฟเวอร์ในขั้นตอนที่ 1

ขั้นตอนที่ 5: เชื่อมโยง passkey

สุดท้าย เชื่อมโยง passkey กับบัญชีผู้ใช้ด้วย endpoint POST /api/my-account/mfa-verifications

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}'

verification_record_id: verification record ID ที่ถูกต้อง ได้จากการยืนยันปัจจัยเดิมของผู้ใช้ ดูรายละเอียดที่ รับรหัสบันทึกการยืนยัน
type: ประเภทของ MFA factor ขณะนี้รองรับเฉพาะ WebAuthn
newIdentifierVerificationRecordId: verification record ID ที่ได้จากเซิร์ฟเวอร์ในขั้นตอนที่ 1

จัดการ WebAuthn passkey ที่มีอยู่

เพื่อจัดการ WebAuthn passkey ที่มีอยู่ ใช้ endpoint GET /api/my-account/mfa-verifications เพื่อดึง passkey และปัจจัย MFA อื่น ๆ ที่มีอยู่

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>'

ตัวอย่าง response:

[
  {
    "id": "...",
    "type": "WebAuthn",
    "name": "...",
    "agent": "...",
    "createdAt": "...",
    "updatedAt": "..."
  }
]

id: รหัสของการยืนยัน
type: ประเภทของการยืนยัน WebAuthn สำหรับ WebAuthn passkey
name: ชื่อของ passkey (ไม่บังคับ)
agent: user agent ของ passkey

อัปเดตชื่อ passkey ด้วย endpoint PATCH /api/my-account/mfa-verifications/{verificationId}/name:

curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"name":"..."}'

ลบ passkey ด้วย endpoint DELETE /api/my-account/mfa-verifications/{verificationId}:

curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

เชื่อมโยง TOTP ใหม่

บันทึก:

อย่าลืม เปิดใช้งาน MFA และ TOTP ก่อน

บันทึก:

เพื่อใช้วิธีนี้ คุณต้องเปิดใช้งานฟิลด์ mfa ใน การตั้งค่า account center

ขั้นตอนที่ 1: สร้าง TOTP secret

ใช้ endpoint POST /api/my-account/mfa-verifications/totp-secret/generate เพื่อสร้าง TOTP secret

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

ตัวอย่าง response:

{
  "secret": "..."
}

ขั้นตอนที่ 2: แสดง TOTP secret ให้ผู้ใช้

นำ secret ไปสร้าง QR code หรือแสดงให้ผู้ใช้โดยตรง ผู้ใช้ควรเพิ่ม secret นี้ในแอป authenticator (เช่น Google Authenticator, Microsoft Authenticator หรือ Authy)

รูปแบบ URI สำหรับ QR code คือ:

otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer]

ตัวอย่าง:

otpauth://totp/YourApp:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

ขั้นตอนที่ 3: ผูก TOTP factor

หลังผู้ใช้เพิ่ม secret ในแอป authenticator แล้ว ต้องยืนยันและผูกกับบัญชีผู้ใช้ ใช้ endpoint POST /api/my-account/mfa-verifications เพื่อผูก TOTP factor

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"Totp","secret":"..."}'

verification_record_id: verification record ID ที่ถูกต้อง ได้จากการยืนยันปัจจัยเดิมของผู้ใช้ ดูรายละเอียดที่ รับรหัสบันทึกการยืนยัน
type: ต้องเป็น Totp
secret: TOTP secret ที่สร้างในขั้นตอนที่ 1

บันทึก:

ผู้ใช้สามารถมี TOTP factor ได้เพียงหนึ่งชุดเท่านั้น หากมีอยู่แล้ว การเพิ่มใหม่จะได้ error 422

จัดการ backup codes

บันทึก:

อย่าลืม เปิดใช้งาน MFA และ backup codes ก่อน

บันทึก:

เพื่อใช้วิธีนี้ คุณต้องเปิดใช้งานฟิลด์ mfa ใน การตั้งค่า account center

ขั้นตอนที่ 1: สร้าง backup codes ใหม่

ใช้ endpoint POST /api/my-account/mfa-verifications/backup-codes/generate เพื่อสร้าง backup codes ชุดใหม่ 10 โค้ด

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

ตัวอย่าง response:

{
  "codes": ["...", "...", "..."]
}

ขั้นตอนที่ 2: แสดง backup codes ให้ผู้ใช้

ก่อนผูก backup codes กับบัญชีผู้ใช้ คุณต้องแสดงโค้ดเหล่านี้ให้ผู้ใช้และแนะนำให้:

ดาวน์โหลดหรือจดโค้ดเหล่านี้ทันที
เก็บไว้ในที่ปลอดภัย
เข้าใจว่าแต่ละโค้ดใช้ได้เพียงครั้งเดียว
ทราบว่าโค้ดเหล่านี้คือทางเลือกสุดท้ายหากสูญเสียการเข้าถึง MFA หลัก

ควรแสดงโค้ดในรูปแบบที่ชัดเจน ง่ายต่อการคัดลอก และอาจมีตัวเลือกดาวน์โหลด (เช่น ไฟล์ข้อความหรือ PDF)

ขั้นตอนที่ 3: ผูก backup codes กับบัญชีผู้ใช้

ใช้ endpoint POST /api/my-account/mfa-verifications เพื่อผูก backup codes กับบัญชีผู้ใช้

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"BackupCode","codes":["...","...","..."]}'

verification_record_id: verification record ID ที่ถูกต้อง ได้จากการยืนยันปัจจัยเดิมของผู้ใช้ ดูรายละเอียดที่ รับรหัสบันทึกการยืนยัน
type: ต้องเป็น BackupCode
codes: อาร์เรย์ของ backup codes ที่สร้างในขั้นตอนก่อนหน้า

บันทึก:

ผู้ใช้สามารถมี backup codes ได้เพียงชุดเดียว หากใช้หมดแล้วต้องสร้างและผูกชุดใหม่
backup codes ไม่สามารถเป็น MFA factor เพียงอย่างเดียวได้ ผู้ใช้ต้องมี MFA factor อื่นอย่างน้อยหนึ่งอย่าง (เช่น WebAuthn หรือ TOTP)
แต่ละ backup code ใช้ได้เพียงครั้งเดียว

ดู backup codes ที่มีอยู่

เพื่อดู backup codes ที่มีอยู่และสถานะการใช้งาน ใช้ endpoint GET /api/my-account/mfa-verifications/backup-codes:

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \
  -H 'authorization: Bearer <access_token>'

ตัวอย่าง response:

{
  "codes": [
    {
      "code": "...",
      "usedAt": null
    },
    {
      "code": "...",
      "usedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

code: backup code
usedAt: เวลาที่ใช้โค้ด ถ้ายังไม่ใช้จะเป็น null

Logto Account API คืออะไร​

วิธีเปิดใช้งาน Account API​

วิธีเข้าถึง Account API​

ดึง access token​

เข้าถึง Account API ด้วย access token​

จัดการข้อมูลบัญชีผู้ใช้พื้นฐาน​

ดึงข้อมูลบัญชีผู้ใช้​

อัปเดตข้อมูลบัญชีผู้ใช้พื้นฐาน​

จัดการ identifier และข้อมูลสำคัญอื่น ๆ​

รับรหัสบันทึกการยืนยัน (verification record id)​

ยืนยันรหัสผ่านผู้ใช้​

ยืนยันโดยส่งโค้ดยืนยันไปยังอีเมลหรือโทรศัพท์ของผู้ใช้​

ส่งคำขอพร้อม verification record id​

อัปเดตรหัสผ่านผู้ใช้​

อัปเดตหรือเชื่อมโยงอีเมลใหม่​

ลบอีเมลของผู้ใช้​

จัดการโทรศัพท์​

เชื่อมโยงบัญชีโซเชียลใหม่​

ลบบัญชีโซเชียล​

เชื่อมโยง WebAuthn passkey ใหม่​

จัดการ WebAuthn passkey ที่มีอยู่​

เชื่อมโยง TOTP ใหม่​

จัดการ backup codes​

Logto Account API คืออะไร

วิธีเปิดใช้งาน Account API

วิธีเข้าถึง Account API

ดึง access token

เข้าถึง Account API ด้วย access token

จัดการข้อมูลบัญชีผู้ใช้พื้นฐาน

ดึงข้อมูลบัญชีผู้ใช้

อัปเดตข้อมูลบัญชีผู้ใช้พื้นฐาน

จัดการ identifier และข้อมูลสำคัญอื่น ๆ

รับรหัสบันทึกการยืนยัน (verification record id)

ยืนยันรหัสผ่านผู้ใช้

ยืนยันโดยส่งโค้ดยืนยันไปยังอีเมลหรือโทรศัพท์ของผู้ใช้

ส่งคำขอพร้อม verification record id

อัปเดตรหัสผ่านผู้ใช้

อัปเดตหรือเชื่อมโยงอีเมลใหม่

ลบอีเมลของผู้ใช้

จัดการโทรศัพท์

เชื่อมโยงบัญชีโซเชียลใหม่

ลบบัญชีโซเชียล

เชื่อมโยง WebAuthn passkey ใหม่

จัดการ WebAuthn passkey ที่มีอยู่

เชื่อมโยง TOTP ใหม่

จัดการ backup codes