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

Logto Account API คืออะไร

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

เข้าถึงโดยตรง: Account API ให้อำนาจผู้ใช้ปลายทางในการเข้าถึงและจัดการโปรไฟล์บัญชีของตนเองโดยตรง โดยไม่ต้องส่งต่อผ่าน Management API
การจัดการโปรไฟล์ผู้ใช้และอัตลักษณ์: ผู้ใช้สามารถจัดการโปรไฟล์และการตั้งค่าความปลอดภัยได้อย่างเต็มที่ รวมถึงการอัปเดตข้อมูลอัตลักษณ์ เช่น อีเมล เบอร์โทรศัพท์ รหัสผ่าน และการจัดการการเชื่อมต่อโซเชียล รองรับ MFA และ SSO เร็วๆ นี้
การควบคุมการเข้าถึงระดับโลก: ผู้ดูแลระบบมีสิทธิ์ควบคุมการเข้าถึงแบบเต็มรูปแบบ และสามารถปรับแต่งแต่ละฟิลด์ได้
การอนุญาต (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 เพื่อเปิดใช้งาน

เมื่อเปิดใช้งานแล้ว ให้กำหนดสิทธิ์แต่ละฟิลด์สำหรับตัวระบุ ข้อมูลโปรไฟล์ และการเข้าถึงโทเค็นของบุคคลที่สาม แต่ละฟิลด์รองรับ 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 = {
  // ...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 ที่เกี่ยวข้องกับอัตลักษณ์และ MFA
    UserScope.Profile, // จัดการโปรไฟล์ผู้ใช้
  ],
};

ดึง 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 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":"..."}'

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

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

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

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

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

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

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

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

บันทึก:

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

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>' \
  -H 'content-type: application/json' \
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}'

เคล็ดลับ:

เช่นเดียวกับอีเมลที่เก็บระหว่างสมัครใช้งาน อีเมลใดๆ ที่เชื่อมโยงผ่าน 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 และตรวจสอบให้แน่ใจว่าได้ตั้งค่าเทมเพลต 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: URL ที่จะ 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 เพื่อเชื่อมโยงการเชื่อมต่อโซเชียล

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

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

จัดการรหัสสำรอง (backup codes)

บันทึก:

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

บันทึก:

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

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

ใช้ endpoint POST /api/my-account/mfa-verifications/backup-codes/generate เพื่อสร้างรหัสสำรองใหม่ 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: แสดงรหัสสำรองให้ผู้ใช้

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

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

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

ขั้นตอนที่ 3: ผูกรหัสสำรองกับบัญชีผู้ใช้

ใช้ 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":"BackupCode","codes":["...","...","..."]}'

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

บันทึก:

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

ดูรหัสสำรองที่มีอยู่

หากต้องการดูรหัสสำรองที่มีอยู่และสถานะการใช้งาน ให้ใช้ 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: รหัสสำรอง
usedAt: เวลาที่ใช้รหัส ถ้ายังไม่ใช้จะเป็น null

Logto Account API คืออะไร​

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

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

ดึง access token​

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

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

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

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

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

รับรหัสบันทึกการยืนยัน (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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

จัดการรหัสสำรอง (backup codes)