การตั้งค่าบัญชีผู้ใช้ด้วย 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 (การยืนยันตัวตนหลายปัจจัย)
จัดการเซสชันผู้ใช้
จัดการแอปที่ผู้ใช้อนุญาต (grants)

หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับ 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 เพื่อเปิดใช้งาน

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

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

วิธีเข้าถึง 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 = {
  // ...other options
  // เพิ่ม 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 ที่เกี่ยวข้องกับ identity และ MFA
    UserScope.Profile, // จัดการ user profile
    UserScope.Sessions, // จัดการ user sessions และ app grants
  ],
};

ดึง access token

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

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

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

คุณควรแนบ access token ในฟิลด์ Authorization ของ HTTP header ด้วยรูปแบบ 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 (profile page 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":"..."}'

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

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

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

ก่อนอื่น คุณต้องขอ verification record ID ที่มีอายุ 10 นาที (TTL) เพื่อใช้ยืนยันตัวตนผู้ใช้ก่อนอัปเดตข้อมูลสำคัญ หมายความว่าเมื่อผู้ใช้ยืนยันตัวตนสำเร็จผ่านรหัสผ่าน, โค้ดยืนยันอีเมล หรือโค้ดยืนยัน SMS แล้ว จะมีเวลา 10 นาทีในการอัปเดตข้อมูลที่เกี่ยวข้องกับการยืนยันตัวตน เช่น identifiers, credentials, การเชื่อมต่อบัญชีโซเชียล และ 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": "..."
}

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

บันทึก:

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

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

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 ของผู้ใช้ได้

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

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

เมื่อส่งคำขอเพื่ออัปเดต identifier ของผู้ใช้ คุณต้องแนบ verification record ID ใน header ของ request ด้วยฟิลด์ 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 จะส่งผลการตรวจสอบและข้อความผิดพลาดโดยละเอียดหากรหัสผ่านไม่ผ่านนโยบาย

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

บันทึก:

เพื่อใช้วิธีนี้ คุณต้อง ตั้งค่า email connector และตรวจสอบให้แน่ใจว่าได้ตั้งค่า template 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

รหัสบันทึกการยืนยัน 2 แบบที่แตกต่างกัน:

คำขอนี้ต้องใช้ 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 connector และตรวจสอบให้แน่ใจว่าได้ตั้งค่า template 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 ที่จะ redirect หลังผู้ใช้อนุญาตแอป คุณควรโฮสต์หน้าเว็บที่ 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 เพื่อเชื่อมโยงการเชื่อมต่อโซเชียล

รหัสบันทึกการยืนยัน 2 แบบที่แตกต่างกัน:

คำขอนี้ต้องใช้ 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 จากโดเมนที่ต่างจากหน้า authentication ของ Logto คุณต้องตั้งค่า Related Origins เพื่ออนุญาตการดำเนินการ passkey ข้ามโดเมน

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 eTLD+1 labels สำหรับ 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

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

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 ได้เพียงหนึ่งชุดเท่านั้น หากมีอยู่แล้ว การเพิ่มใหม่จะได้ error 422

แทนที่ TOTP ที่มีอยู่

หากผู้ใช้มีปัจจัย TOTP อยู่แล้ว คุณสามารถแทนที่ด้วยชุดใหม่โดยใช้ endpoint PUT /api/my-account/mfa-verifications/totp การดำเนินการนี้เป็น idempotent คือจะลบ TOTP เดิมและผูกชุดใหม่

บันทึก:

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

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

ใช้ endpoint POST /api/my-account/mfa-verifications/totp-secret/generate เพื่อสร้าง TOTP secret ใหม่ แล้วแสดงให้ผู้ใช้ตามขั้นตอนใน เชื่อมโยง TOTP ใหม่

ขั้นตอนที่ 2: แทนที่ปัจจัย TOTP

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

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

จัดการ 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

จัดการการตั้งค่าการยืนยัน 2 ขั้นตอน

บันทึก:

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

ผู้ใช้ปลายทางสามารถเปิด/ปิดการยืนยัน 2 ขั้นตอนสำหรับบัญชีของตนเองได้ กรณีใช้งานที่พบบ่อยคือเมื่อผู้ใช้ตั้งค่า MFA factor (เช่น passkey) แล้วแต่ต้องการใช้เฉพาะสำหรับการลงชื่อเข้าใช้ ไม่ใช่เป็นขั้นตอนยืนยันเพิ่มเติม — การปิด 2-step verification จะช่วยให้ข้าม MFA prompt ระหว่างลงชื่อเข้าใช้ได้โดยยังคงมี MFA factor อยู่ การตั้งค่านี้ควบคุมโดย skipMfaOnSignIn ต่อผู้ใช้แต่ละราย

ดึงการตั้งค่า MFA ปัจจุบัน

ใช้ endpoint GET /api/my-account/mfa-settings เพื่อดึงการตั้งค่าการยืนยัน 2 ขั้นตอนของผู้ใช้

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

ตัวอย่าง response:

{
  "skipMfaOnSignIn": false
}

อัปเดตการตั้งค่า MFA

เพื่อเปิดหรือปิด 2-step verification ใช้ endpoint PATCH /api/my-account/mfa-settings

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

verification_record_id: verification record ID ที่ถูกต้อง ดูรายละเอียดที่ รับรหัสบันทึกการยืนยัน
skipMfaOnSignIn: ตั้งค่าเป็น true เพื่อปิด 2-step verification หรือ false เพื่อเปิด

บันทึก:

การตั้งค่านี้จะมีผลเฉพาะเมื่อ MFA policy ถูกตั้งเป็น Optional หาก MFA เป็น Mandatory หรือ Adaptive การตั้งค่า skipMfaOnSignIn จะถูกละเว้นและ MFA จะถูกบังคับใช้

จัดการเซสชันผู้ใช้

แสดงรายการเซสชันที่ใช้งานอยู่

เพื่อแสดงรายการเซสชันที่ใช้งานของผู้ใช้ ใช้ endpoint GET /api/my-account/sessions

บันทึก:

ต้องใช้ scope UserScope.Sessions เพื่อเข้าถึง endpoint นี้
ฟิลด์ Sessions ในการตั้งค่า account center ต้องตั้งเป็น ReadOnly หรือ Edit

curl https://[tenant-id].logto.app/api/my-account/sessions \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

เพิกถอนเซสชันด้วย session ID

เพื่อเพิกถอนเซสชันเฉพาะ ใช้ endpoint DELETE /api/my-account/sessions/{sessionId}

บันทึก:

ต้องใช้ scope UserScope.Sessions เพื่อเข้าถึง endpoint นี้
ฟิลด์ Sessions ในการตั้งค่า account center ต้องตั้งเป็น Edit

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

พารามิเตอร์ query เสริม:

revokeGrantsTarget: ระบุเป้าหมายของ grants ที่จะเพิกถอนพร้อมกับเซสชัน ค่าได้แก่:
- all: เพิกถอน grants ทั้งหมดที่เกี่ยวข้องกับเซสชัน
- firstParty: เพิกถอนเฉพาะ app grants ของ first-party ที่เกี่ยวข้องกับเซสชัน (แนะนำสำหรับกรณีส่วนใหญ่ เพราะจะเพิกถอนการเข้าถึงเฉพาะแอปของคุณเองโดยยังคง grants ของ third-party ไว้ เพื่อประสบการณ์ผู้ใช้ที่ดีกว่า)
- ไม่ระบุ: พฤติกรรมเริ่มต้นจะเพิกถอน grants ที่ไม่มี scope offline_access ซึ่งโดยทั่วไปหมายถึงการเพิกถอน grants ที่ไม่ใช่ refresh-token สำหรับเซสชันนั้น

จัดการแอปที่ผู้ใช้อนุญาต (grants)

ใช้ API แอปที่ผู้ใช้อนุญาต (grants) เมื่อผู้ใช้ต้องการตรวจสอบและเพิกถอนแอปที่อนุญาตจากหน้าตั้งค่าบัญชีของตน

บันทึก:

API grant ใช้โมเดลสิทธิ์เดียวกับ session API
ต้องใช้ scope UserScope.Sessions
ฟิลด์ Sessions ในการตั้งค่า account center ต้องเปิดใช้งาน:
- ReadOnly หรือ Edit เพื่อแสดงรายการ grants
- Edit เพื่อเพิกถอน grants

แสดงรายการ app grants ที่ใช้งานอยู่

เพื่อแสดงรายการ app grants ที่ใช้งานของผู้ใช้ปัจจุบัน ใช้ endpoint GET /api/my-account/grants

curl https://[tenant-id].logto.app/api/my-account/grants \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

พารามิเตอร์ query เสริม:

appType=firstParty: คืนเฉพาะ app grants ของ first-party
appType=thirdParty: คืนเฉพาะ app grants ของ third-party
ไม่ระบุ appType: คืน grants ทั้งหมดที่ใช้งานอยู่

curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

เพิกถอน app grant ด้วย grant ID

เพื่อเพิกถอน app grant เฉพาะ ใช้ endpoint DELETE /api/my-account/grants/{grantId}

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

เมื่อ grant ถูกเพิกถอน โทเค็นทึบ (opaque access tokens) และโทเค็นรีเฟรช (refresh tokens) ที่ออกให้ก่อนหน้านี้สำหรับ grant นั้นจะถูกทำให้ใช้ไม่ได้

Logto Account API คืออะไร​

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

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

ดึง access token​

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

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

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

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

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

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

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

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

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

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

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

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

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

เชื่อมโยงการเชื่อมต่อโซเชียลใหม่​

ลบการเชื่อมต่อโซเชียล​

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

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

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

แทนที่ TOTP ที่มีอยู่​

จัดการ backup codes​

จัดการการตั้งค่าการยืนยัน 2 ขั้นตอน​

จัดการเซสชันผู้ใช้​

จัดการแอปที่ผู้ใช้อนุญาต (grants)​

Logto Account API คืออะไร

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

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

ดึง access token

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

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

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

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

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

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

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

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

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

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

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

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

จัดการเบอร์โทรศัพท์

เชื่อมโยงการเชื่อมต่อโซเชียลใหม่

ลบการเชื่อมต่อโซเชียล

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

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

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

แทนที่ TOTP ที่มีอยู่

จัดการ backup codes

จัดการการตั้งค่าการยืนยัน 2 ขั้นตอน

จัดการเซสชันผู้ใช้

จัดการแอปที่ผู้ใช้อนุญาต (grants)