การตั้งค่าบัญชีผู้ใช้ด้วย 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 API เท่านั้น ดูรายละเอียดการใช้งานได้ที่ การตั้งค่าบัญชีผู้ใช้ด้วย 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 ใหม่
ฟิลด์โปรไฟล์:
- ฟิลด์ประกอบด้วย: ชื่อผู้ใช้, ชื่อ, อวาตาร์, โปรไฟล์ (แอตทริบิวต์โปรไฟล์มาตรฐานอื่น ๆ) และ ข้อมูลกำหนดเอง
- ผู้ใช้ปลายทางสามารถแก้ไขฟิลด์เหล่านี้ได้โดยไม่ต้องยืนยันตัวตนเพิ่มเติม
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 (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":"..."}'

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

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

หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับการยืนยัน โปรดดู 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":"..."}'

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

บันทึก:

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

เพื่อเชื่อมโยงบัญชีโซเชียลใหม่ ก่อนอื่นคุณต้องขอ 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 ใน การตั้งค่า 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 ข้ามโดเมน

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

ดูข้อมูลเพิ่มเติมเกี่ยวกับ 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/[ผู้ออก]:[บัญชี]?secret=[Secret]&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 ที่ถูกต้อง โดยได้จากการยืนยันปัจจัยเดิมของผู้ใช้ ดูรายละเอียดที่ รับรหัสบันทึกการยืนยัน
type: ต้องเป็น Totp
secret: TOTP secret ที่สร้างในขั้นตอนที่ 1

บันทึก:

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

ดึง 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