การตั้งค่าบัญชีผู้ใช้ด้วย 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>

บันทึก:

เพื่อให้แน่ใจว่าโทเค็นการเข้าถึงมีสิทธิ์ที่เหมาะสม โปรดตรวจสอบว่าคุณได้กำหนดค่า 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, // สำหรับ API `{POST,DELETE} /api/my-account/primary-email`
    UserScope.Phone, // สำหรับ API `{POST,DELETE} /api/my-account/primary-phone`
    UserScope.CustomData, // จัดการ custom data
    UserScope.Address, // จัดการที่อยู่
    UserScope.Identities, // สำหรับ API ที่เกี่ยวกับอัตลักษณ์และ MFA
    UserScope.Profile, // จัดการโปรไฟล์ผู้ใช้
  ],
};

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

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

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

ศึกษารายละเอียด API เพิ่มเติมได้ที่ Logto Account API Reference และ Logto Verification API Reference

บันทึก:

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

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

โดยปกติ Account API จะถูกปิดใช้งาน คุณต้องใช้ Management API เพื่ออัปเดตการตั้งค่าระดับโลก

API endpoint /api/account-center ใช้สำหรับดึงและอัปเดตการตั้งค่าศูนย์บัญชี (account center) คุณสามารถใช้เพื่อเปิด / ปิด Account API และปรับแต่งฟิลด์ต่างๆ ได้

ตัวอย่างการร้องขอ:

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token for Logto Management API>' \
  -H 'content-type: application/json' \
  --data-raw '{"enabled":true,"fields":{"username":"Edit"}}'

ฟิลด์ enabled ใช้สำหรับเปิด / ปิด Account API และฟิลด์ fields ใช้สำหรับปรับแต่งฟิลด์ต่างๆ โดยค่าที่เป็นไปได้คือ Off, Edit, ReadOnly ค่าเริ่มต้นคือ Off รายการฟิลด์ที่รองรับ:

name: ฟิลด์ชื่อ
avatar: ฟิลด์อวาตาร์
profile: ฟิลด์โปรไฟล์ รวมถึงฟิลด์ย่อย
username: ฟิลด์ชื่อผู้ใช้
email: ฟิลด์อีเมล
phone: ฟิลด์เบอร์โทรศัพท์
password: ฟิลด์รหัสผ่าน เมื่อดึงข้อมูลจะคืนค่า true หากผู้ใช้ตั้งรหัสผ่านไว้แล้ว มิฉะนั้นเป็น false
social: การเชื่อมต่อโซเชียล
mfa: ปัจจัย MFA

ศึกษารายละเอียด API เพิ่มเติมได้ที่ Logto Management API Reference

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

ดึงโทเค็นการเข้าถึง

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

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

เข้าถึง Account API ด้วยโทเค็นการเข้าถึง

คุณควรแนบโทเค็นการเข้าถึงในฟิลด์ 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 อาจแตกต่างกันไปตามการตั้งค่าศูนย์บัญชี

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

ข้อมูลบัญชีพื้นฐานประกอบด้วย ชื่อผู้ใช้ ชื่อ อวาตาร์ 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": "..."
}

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

บันทึก:

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

ศึกษาข้อมูลเพิ่มเติมเกี่ยวกับการยืนยันได้ที่ การยืนยันความปลอดภัยด้วย Account API

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

เมื่อส่งคำร้องขอเพื่ออัปเดตตัวระบุของผู้ใช้ คุณต้องแนบ 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":"..."}'

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

บันทึก:

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

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

เพื่อลบอีเมลของผู้ใช้ ใช้ 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 เพื่อลบเบอร์โทรศัพท์ของผู้ใช้

เพื่อเชื่อมโยงบัญชีโซเชียลใหม่ ให้ขอ URL การอนุญาต (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: รหัสของ ตัวเชื่อมต่อโซเชียล
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 คือข้อมูลที่ตัวเชื่อมต่อโซเชียลส่งกลับหลังผู้ใช้อนุญาตแอป คุณต้องแยก 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 ใน การตั้งค่าศูนย์บัญชี

ขั้นตอนที่ 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 ข้าม 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 ของคุณ เช่น หากศูนย์บัญชีของแอปรันที่ 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"]}'

ศึกษาข้อมูลเพิ่มเติมเกี่ยวกับ 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 ที่ถูกต้อง ซึ่งได้จากการยืนยันปัจจัยเดิมของผู้ใช้ ดูรายละเอียดที่ รับ verification record ID
type: ประเภทของปัจจัย MFA ปัจจุบันรองรับเฉพาะ 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 ใน การตั้งค่าศูนย์บัญชี

ขั้นตอนที่ 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

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 ที่ถูกต้อง ซึ่งได้จากการยืนยันปัจจัยเดิมของผู้ใช้ ดูรายละเอียดที่ รับ verification record ID
type: ต้องเป็น Totp
secret: TOTP secret ที่สร้างในขั้นตอนที่ 1

บันทึก:

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

จัดการ backup codes

บันทึก:

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

บันทึก:

หากใช้วิธีนี้ คุณต้องเปิดใช้งานฟิลด์ mfa ใน การตั้งค่าศูนย์บัญชี

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

บันทึก:

ผู้ใช้สามารถมี backup codes ได้เพียงชุดเดียว หากใช้หมดแล้วต้องสร้างและผูกใหม่
backup codes ไม่สามารถเป็นปัจจัย MFA เพียงอย่างเดียวได้ ผู้ใช้ต้องมีปัจจัย MFA อื่นอย่างน้อยหนึ่งรายการ (เช่น 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​

ดึงโทเค็นการเข้าถึง​

เข้าถึง Account API ด้วยโทเค็นการเข้าถึง​

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

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

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

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

รับ verification record id​

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

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

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

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

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

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

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

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

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

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

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

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

จัดการ backup codes​

Logto Account API คืออะไร

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

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

ดึงโทเค็นการเข้าถึง

เข้าถึง Account API ด้วยโทเค็นการเข้าถึง

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

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

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

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

รับ verification record id

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

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

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

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

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

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

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

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

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

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

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

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

จัดการ backup codes