ข้ามไปยังเนื้อหาหลัก

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

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

  1. ฟิลด์ความปลอดภัย:
    • ฟิลด์ประกอบด้วย: อีเมลหลัก, เบอร์โทรหลัก, อัตลักษณ์โซเชียล, รหัสผ่าน, passkeys, MFA และ personal access tokens
    • การดำเนินการที่ละเอียดอ่อนต้องการการยืนยันตัวตนล่าสุดของผู้ใช้จากแอป first-party — โทเค็นการเข้าถึงที่ acr ตรงตาม urn:logto:acr:1fa ภายในช่วงเวลาที่ตั้งค่าไว้ (ดู OIDC step-up authentication)
    • หากต้องการใช้ WebAuthn passkeys สำหรับ MFA ให้เพิ่มโดเมนแอป front-end ของคุณใน WebAuthn Related Origins เพื่อให้ account center และประสบการณ์ลงชื่อเข้าใช้สามารถใช้ passkeys ร่วมกันได้ ดู เชื่อมโยง WebAuthn passkey ใหม่
  2. ฟิลด์โปรไฟล์:
    • ฟิลด์ประกอบด้วย: username, name, avatar, profile (แอตทริบิวต์โปรไฟล์มาตรฐานอื่น ๆ) และ custom data
    • ผู้ใช้ปลายทางสามารถแก้ไขฟิลด์เหล่านี้ได้โดยไม่ต้องยืนยันเพิ่มเติม ยกเว้น username ที่ต้องการการยืนยันตัวตนล่าสุดเช่นกัน
  3. Secret vault:
    • สำหรับ OIDC หรือ OAuth social และ enterprise connectors, Logto secret vault จะเก็บ access token และ refresh token ของบุคคลที่สามอย่างปลอดภัยหลังการยืนยันตัวตน แอปสามารถเรียก API ภายนอก เช่น ซิงค์กิจกรรม Google Calendar ได้โดยไม่ต้องให้ผู้ใช้ลงชื่อเข้าใช้ซ้ำ การดึงโทเค็นจะพร้อมใช้งานโดยอัตโนมัติเมื่อเปิด Account API
  4. การจัดการเซสชัน:
    • เมื่อเปิดใช้งาน ผู้ใช้สามารถดูและจัดการเซสชันที่ใช้งานอยู่ รวมถึงข้อมูลอุปกรณ์และเวลาลงชื่อเข้าใช้ล่าสุด ผู้ใช้ยังสามารถเพิกถอนเซสชันเพื่อออกจากอุปกรณ์เฉพาะได้
    • สิทธิ์ฟิลด์ Sessions นี้ยังควบคุม API แอปที่ผู้ใช้อนุญาต (grants) ด้วย (ดูและเพิกถอน grants)
    • การเข้าถึงการจัดการเซสชันและ grant ต้องการการยืนยันตัวตนล่าสุดเช่นเดียวกับฟิลด์ความปลอดภัย

วิธีเข้าถึง 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, // จัดการโปรไฟล์ผู้ใช้
    UserScope.Sessions, // จัดการเซสชันผู้ใช้และ app grants
  ],
};

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

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

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

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

ด้วยเหตุผลด้านความปลอดภัย การดำเนินการที่ละเอียดอ่อนของ Account API ต้องการการยืนยันตัวตนล่าสุดของผู้ใช้จากแอป first-party: access token ต้องมี acr ที่ตรงตาม urn:logto:acr:1fa และ auth_time อยู่ในช่วง Recent authentication ของ tenant (600 วินาที / 10 นาทีโดยค่าเริ่มต้น ปรับได้ตั้งแต่ 60 ถึง 7,200 วินาที)

หาก access token ไม่มี urn:logto:acr:1fa หรือหมดอายุเกินช่วงเวลาดังกล่าว Account API จะคืนค่า 401 Unauthorized พร้อม header WWW-Authenticate ตาม RFC 9470 (error="insufficient_user_authentication", acr_values="urn:logto:acr:1fa", max_age="<window>") ให้เริ่ม OIDC step-up authentication ด้วยพารามิเตอร์เหล่านั้นและลองใหม่ด้วย access token ที่ออกใหม่

บันทึก:

การผูก อีเมล เบอร์โทร อัตลักษณ์โซเชียล หรือ WebAuthn passkey ใหม่ ต้องพิสูจน์ความเป็นเจ้าของ identifier หรือ factor ใหม่นั้นผ่าน Verification API และส่ง newIdentifierVerificationRecordId ใน request body ตามแต่ละหัวข้อด้านล่าง

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

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

curl -X POST https://[tenant-id].logto.app/api/my-account/password \
  -H 'authorization: Bearer <access_token>' \
  -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

curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'
เคล็ดลับ:

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

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

เพื่อลบอีเมลของผู้ใช้ ใช้ 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>'

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

บันทึก:

เพื่อใช้วิธีนี้ คุณต้อง ตั้งค่า 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: 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 'content-type: application/json' \
  --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>'
บันทึก:

อย่าลืม เปิดใช้งาน 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"]}'
บันทึก:

WebAuthn รองรับได้สูงสุด 5 eTLD+1 labels สำหรับ Related Origins โดย eTLD+1 คือส่วนโดเมนที่ลงทะเบียนได้ เช่น:

  • 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 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 'content-type: application/json' \
  --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}'
  • 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 (optional)
  • 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 '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>'
บันทึก:

อย่าลืม เปิดใช้งาน 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:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

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

หลังผู้ใช้เพิ่ม 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 'content-type: application/json' \
  --data-raw '{"type":"Totp","secret":"..."}'
  • type: ต้องเป็น Totp
  • secret: TOTP secret ที่สร้างในขั้นตอนที่ 1
บันทึก:

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

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

หากผู้ใช้มี TOTP factor อยู่แล้ว สามารถแทนที่ด้วยอันใหม่โดยใช้ 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 factor

curl -X PUT https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"secret":"...","code":"..."}'
  • 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 'content-type: application/json' \
  --data-raw '{"type":"BackupCode","codes":["...","...","..."]}'
  • 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 'content-type: application/json' \
  --data-raw '{"skipMfaOnSignIn":true}'
  • skipMfaOnSignIn: ตั้งค่าเป็น true เพื่อปิด 2-step verification หรือ false เพื่อเปิด
บันทึก:

การตั้งค่านี้มีผลเฉพาะเมื่อ MFA policy เป็น Optional หาก MFA เป็น Mandatory หรือ Adaptive การตั้งค่านี้จะถูกละเว้นและ 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 '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 'content-type: application/json'

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

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

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

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

บันทึก:
  • API grant ใช้โมเดลสิทธิ์เดียวกับ API session
  • ต้องใช้ 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 '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 '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 'content-type: application/json'

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