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

ทุกเส้นยกเว้น GET /v1/openapi.json ต้องใช้กุญแจ API กุญแจใบเดียวถือทั้งตัวตนและสิทธิ์ของคุณ สิ่งที่กุญแจอ่านได้ถูกกำหนดตั้งแต่ตอนออกใบ และไม่มีอะไรที่ใส่ลงไปในคำขอแล้วขยายสิทธิ์ได้

ส่งกุญแจเป็น bearer token

Authorization: Bearer sf_live_XXXXXXXXXXXX_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

curl -s https://api.scanfood.co/ext/v1/shops \
  -H "Authorization: Bearer $SCANFOOD_API_KEY"

const res = await fetch('https://api.scanfood.co/ext/v1/shops', {
  headers: { Authorization: `Bearer ${process.env.SCANFOOD_API_KEY}` },
});

headers = {"Authorization": f"Bearer {os.environ['SCANFOOD_API_KEY']}"}
r = requests.get("https://api.scanfood.co/ext/v1/shops", headers=headers, timeout=30)

ส่วนหัวคือช่องทางเดียวที่รับ กุญแจที่ใส่มาใน query string หรือใน body จะถูกมองข้าม และคำขอนั้นถูกตอบเหมือนไม่ได้ส่งกุญแจมาเลย เหตุผลคือ query string ไปโผล่ใน access log ของทุกชั้นที่คั่นกลาง ส่วน body ไปโผล่ในระบบติดตามการทำงาน

กุญแจหนึ่งใบมีสามส่วน

ขอบเขตถูกกำหนดตอนออกใบ และถูกตรวจทุกคำขอ ไม่มีอะไรในคำขอที่เปลี่ยนมันได้

ผลที่ตามมาในทางปฏิบัติ

• GET /v1/shops ไม่รับพารามิเตอร์ใด ๆ มันคืนสาขาที่กุญแจอ่านได้ จึงเป็นวิธีที่เร็วที่สุดในการดูว่ากุญแจใบหนึ่งทำอะไรได้บ้าง สาขาที่ถูกลบไปแล้ว จะหลุดออกจากลิสต์นี้ทั้งที่ยังอยู่ในขอบเขตของกุญแจ ให้อ่านลิสต์นี้ว่า “มีอะไรให้อ่านบ้าง” ไม่ใช่นิยามของขอบเขตแบบตรงตัว
• ส่ง shopId ที่อยู่นอกขอบเขตจะได้ 403 shop_not_in_scope และส่ง providerId ที่อยู่นอกขอบเขตจะได้ 403 provider_not_in_scope เส้นแบบลิสต์ตอบ 403 ไม่ใช่ 404 เพราะรหัสที่คุณส่งมาเป็นรหัสที่คุณรู้อยู่แล้ว
• ส่วนการขอบิลใบเดียวหรือสมาชิกคนเดียวที่อยู่นอกขอบเขต จะได้ 404 not_found เพราะเราไม่ยืนยันว่ารหัสนั้นมีอยู่จริงในร้านที่คุณอ่านไม่ได้

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

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

1. ขอกุญแจ ใบที่สอง จาก ScanFood ด้วยขอบเขตเดียวกัน
2. นำไปติดตั้งในระบบของคุณ แล้วยืนยันว่ามีคำขอวิ่งด้วยกุญแจใบใหม่จริง
3. แจ้งให้ยกเลิกกุญแจใบเก่า

เก็บกุญแจไว้ที่เดียวกับที่ระบบของคุณเก็บความลับอื่นอยู่แล้ว อย่า commit ลง repo อย่าวางลงในใบงาน และอย่าส่งทางอีเมล ถ้ากุญแจหลุด ให้ถือว่าเป็นการเปลี่ยนกุญแจหนึ่งรอบ คือออกใบใหม่ ติดตั้ง แล้วยกเลิกใบเก่า

การยกเลิกเป็นการถาวร กุญแจที่ยกเลิกแล้วเปิดกลับมาใช้ไม่ได้ ต้องออกใบใหม่แทน ส่วนการยกเลิกใบที่ยกเลิกไปแล้วไม่มีผลเสียอะไร

คำขอที่ใช้กุญแจที่ถูกยกเลิกจะได้ 401 key_revoked ซึ่งเป็นคนละรหัสกับ invalid_key โดยเจตนา เพราะมีแต่ผู้ถือรหัสลับที่ถูกต้องเท่านั้นที่จะเห็นข้อความนี้ มันจึงบอกว่า “กุญแจใบนี้ถูกปลดระวางแล้ว” แทนที่จะส่งคุณไปไล่หาว่าพิมพ์อะไรผิด

คำตอบ 401 ไม่มีส่วนหัวบอกโควตาติดมาด้วย เพราะระบบตรวจกุญแจก่อนตรวจโควตา ดูความหมายของส่วนหัวเหล่านั้นได้ที่ ขีดจำกัดการเรียก และดูรหัสอื่นทั้งหมดที่ ข้อผิดพลาด