การยืนยันตัวตน

ก่อนเริ่ม

คุณต้องมีบัญชีสำหรับระบบภายนอก (service account) ที่ผู้ดูแลระบบสร้างให้ ห้ามใช้บัญชีของพนักงานจริงเรียก API เพราะเมื่อพนักงานลาออกและบัญชีถูกปิด การเชื่อมต่อจะล่มพร้อมกันโดยไม่มีใครรู้ว่าเกี่ยวข้องกัน

บัญชีนั้นต้องมี บทบาทเท่าที่จำเป็นจริง — token ไม่มีขอบเขต (scope) ของตัวเอง สิทธิ์ของ token เท่ากับสิทธิ์ของบัญชีที่ถืออยู่ทุกประการ ทั้งบทบาทและ User Permission การจำกัดสิทธิ์จึงต้องทำที่บัญชี ไม่ใช่ที่ token

ขั้นตอน

1. ผู้ดูแลระบบเปิดเอกสารผู้ใช้ของ service account ไปที่หัวข้อ API Access แล้วสั่งสร้างคู่กุญแจ ระบบจะเก็บ API Key ไว้ในเอกสารและแสดง API Secret ให้เห็น ครั้งเดียว ในกล่องข้อความ

   คัดลอก API Secret ตอนนั้นเลย

   ค่านี้ถูกเก็บแบบเข้ารหัส เปิดดูย้อนหลังไม่ได้ ถ้าพลาดต้องสั่งสร้างใหม่ ซึ่งจะทำให้ค่าเดิมใช้ไม่ได้ทันทีและระบบที่ใช้อยู่จะล่ม

2. ใช้ทั้งคู่ในส่วนหัว Authorization โดยคั่นด้วยเครื่องหมายทวิภาค

   Authorization: token <API Key>:<API Secret>

   รูปแบบ Basic <base64 ของ key:secret> ก็ใช้ได้เช่นกัน ระบบยอมรับทั้งสองแบบ ส่วน Bearer <token> สงวนไว้สำหรับ OAuth ซึ่งเป็นคนละกลไก

3. เก็บ token ไว้ในที่เก็บความลับของฝั่งเซิร์ฟเวอร์ ไม่ใส่ในโค้ดฝั่งเบราว์เซอร์และไม่ commit ลง git

คู่กุญแจนี้ไม่มีวันหมดอายุ

ต่างจาก access token ทั่วไปตรงที่ไม่มีรอบต่ออายุ มันใช้ได้จนกว่าจะมีคนสั่งสร้างใหม่ หรือปิดบัญชี อย่าเขียนโค้ดที่รอ 401 แล้วไปเรียก endpoint ต่ออายุ — ไม่มี endpoint นั้น และถ้าเจอ 401 จริงแปลว่าคู่กุญแจถูกเปลี่ยนหรือบัญชีถูกปิด ซึ่งต้องมีคนเข้าไปแก้

ผลตามมาที่สำคัญกว่า: token ที่หลุดจะใช้ได้ตลอดไป จนกว่าจะมีคนรู้ตัวและเพิกถอน จึงควรหมุนกุญแจตามรอบที่กำหนดเอง ไม่ใช่รอให้ระบบเตือน

แอปมือถือ KlevIQ Flow ใช้กลไกเดียวกัน

kleviq_flow.api.login รับอีเมลกับรหัสผ่านแล้วคืนค่าที่หน้าตาเหมือน access token พร้อมวันหมดอายุ — แต่ข้างในคือคู่ API Key:API Secret ของผู้ใช้คนนั้นเอง วันหมดอายุที่ส่งกลับมาเป็นเพียงตัวเลขที่แอปเอาไปใช้ตั้งเวลาถามซ้ำ ไม่ใช่วันหมดอายุจริง และการเรียก refresh_access_token จะได้ค่าเดิมกลับมา ไม่มีการหมุนกุญแจ

ตรวจว่าถูกต้องแล้ว

เรียกอย่างใดอย่างหนึ่ง

GET /api/method/frappe.auth.get_logged_user

ต้องได้ 200 พร้อมอีเมลของ service account — ถ้าได้อีเมลของคนอื่นหรือได้ Guest แปลว่าส่วนหัวไม่ถูกใช้และคุณกำลังเรียกแบบไม่ยืนยันตัวตนอยู่

ถ้าไซต์ติดตั้ง kleviq_bridge ไว้ จะมี endpoint ที่บอกบริบทครบกว่านั้น

GET /api/method/kleviq_bridge.api.identity.whoami

คืนค่าผู้ใช้ที่เชื่อมต่ออยู่ รายการบทบาททั้งหมดของบัญชีนั้น รายชื่อบริษัท ปีบัญชี และเลขรุ่นของแอปในไซต์ — ใช้ตอนตั้งค่าครั้งแรกเพื่อยืนยันว่าต่อถูกไซต์และได้สิทธิ์ตามที่ตกลง

200 ไม่ได้แปลว่าสิทธิ์ครบ

คำขออ่านรายการที่บัญชีไม่มีสิทธิ์ มักคืน 200 พร้อม รายการว่าง ไม่ใช่ 403 การทดสอบว่า "เรียกได้" จึงไม่พอ ต้องทดสอบว่า "ได้ข้อมูลที่คาดว่าจะได้" ด้วย

เมื่อ token รั่ว

1. สั่งสร้างคู่กุญแจใหม่ทันที ที่เอกสารผู้ใช้ของ service account — ค่าเดิมใช้ไม่ได้ ตั้งแต่วินาทีนั้น ไม่มีช่วงผ่อนผัน ระบบที่ยังใช้ค่าเก่าจะเริ่มได้ 401 ทันที ให้เตรียมที่ทางเปลี่ยนค่าในระบบปลายทางไว้ก่อนกด
2. ถ้าต้องตัดขาดเดี๋ยวนั้นและยังไม่พร้อมออกกุญแจใหม่ ให้ถอดติ๊ก Enabled ที่บัญชีแทน
3. ตรวจย้อนหลังว่ามีอะไรถูกแตะ — ดูรายการเอกสารที่มีบัญชีนั้นเป็นผู้แก้ไขล่าสุด และให้ผู้ดูแลระบบเปิด Activity Log ในช่วงเวลาที่สงสัย
4. หลังกู้เสร็จ ทบทวนว่าบัญชีนั้นมีบทบาทเกินความจำเป็นหรือไม่ — token ที่รั่วแล้วเสียหายน้อย คือ token ที่ทำได้น้อยตั้งแต่แรก

อ่านต่อ

• ภาพรวม API
• จัดสิทธิ์ผู้ใช้