การยืนยันตัวตน
ทุกคำขอไปยัง Sursa API ต้องมีคีย์ API หรือโทเค็นเข้าถึง OAuth (access token) ของแอปพลิเคชันในเฮดเดอร์ Authorization:
Authorization: Bearer kb_3f9c…
คีย์ระบุองค์กร และกำหนดว่าคำขอมองเห็นและเปลี่ยนแปลงอะไรได้บ้าง ผ่านบทบาท ขอบเขตสิทธิ์ โปรไฟล์ข้อมูล และคอลเลกชันของคีย์ ที่อยู่ API ไม่มีเซสชันและคุกกี้ แต่ละคำขอยืนยันตัวตนด้วยตัวเอง คุณจึงส่งคำขอพร้อมกันหลายคำขอและจากเซิร์ฟเวอร์หลายเครื่องด้วยคีย์เดียวกันได้
curl https://api.sursa.com/v1/me \
-H "Authorization: Bearer $SURSA_API_KEY"ระบบที่เชื่อมต่อรุ่นก่อนอาจส่งคีย์ในเฮดเดอร์ X-API-Key แทน ซึ่งระบบยังยอมรับอยู่ แต่โค้ดใหม่ควรใช้ Authorization: Bearer
ประเภทของข้อมูลรับรอง
| ข้อมูลรับรอง | ลักษณะ | ใช้ได้ที่ใด |
|---|---|---|
| คีย์ API ขององค์กร | kb_… | ทุกเอนด์พอยต์ของ API ภายในขอบเขตของบทบาท ขอบเขตสิทธิ์ โปรไฟล์ข้อมูล และคอลเลกชันของคีย์ |
| คีย์แหล่งข้อมูล | kbsrc_… | เฉพาะเอนด์พอยต์สำหรับส่ง (push) ของ แหล่งข้อมูลแบบกำหนดเอง ของคีย์นั้นเอง (/v1/push/sources/{source_id}/…) |
| โทเค็นเข้าถึง OAuth | kbat_… | เอนด์พอยต์ใน เอกสารอ้างอิง API ภายในขอบเขตสิทธิ์ของโทเค็น โทเค็นที่ได้จาก POST /oauth/token ด้วยรหัสการอนุญาตทำงานในนามของพนักงานที่ให้ความยินยอม ส่วนโทเค็น client_credentials ทำงานในนามขององค์กรเหมือนคีย์ API โทเค็นมีอายุ 1 ชั่วโมง |
ทุกแบบส่งด้วยวิธีเดียวกัน คีย์แหล่งข้อมูลอ่าน ค้นหา หรือเปลี่ยนแปลงสิ่งใดนอกแหล่งข้อมูลของตัวเองไม่ได้ ให้ใช้คีย์นี้ในที่ที่บุคคลภายนอกเป็นผู้เก็บคีย์ เช่น แพลตฟอร์มเชื่อมต่อระบบ
ข้อผิดพลาดในการยืนยันตัวตน
| สถานะและรหัส | ความหมาย | สิ่งที่ต้องทำ |
|---|---|---|
401 auth.not_authenticated | ไม่มีคีย์ คีย์พิมพ์ผิด หรือคีย์ถูกเพิกถอนแล้ว | ตรวจเฮดเดอร์และค่าของคีย์ |
401 api_keys.expired | คีย์เลยวันหมดอายุแล้ว | สร้างคีย์ใหม่และใช้แทนคีย์เดิม |
401 sources.push_key_invalid | คีย์แหล่งข้อมูลไม่ถูกต้อง ถูกเพิกถอน หรือเป็นของแหล่งข้อมูลอื่น | ตรวจคีย์และ ID ของแหล่งข้อมูลในพาธ |
401 oauth.token_expired | โทเค็นเข้าถึง OAuth หมดอายุแล้ว | ขอโทเค็นใหม่ด้วยโทเค็นรีเฟรช (refresh token) |
403 api_keys.scope | คีย์ไม่มีขอบเขตสิทธิ์สำหรับการดำเนินการนี้ | เพิ่มขอบเขตสิทธิ์ หรือใช้คีย์ที่มีขอบเขตสิทธิ์นั้น |
403 api_keys.feature_disabled | แพ็กเกจขององค์กรไม่รวมคีย์ API | ติดต่อผู้ดูแลระบบขององค์กร |
403 api_keys.ip_not_allowed | คำขอมาจากที่อยู่ IP ที่อยู่นอกรายการที่อยู่ที่คีย์อนุญาต | เรียกจากเครือข่ายที่อนุญาต หรือเปลี่ยนรายการที่อยู่ของคีย์ |
403 api_keys.mcp_only | มีการใช้คีย์ MCP ส่วนตัวนอกเอนด์พอยต์ /mcp | ใช้คีย์ API ขององค์กรสำหรับ API |
403 oauth.operation_not_allowed | การดำเนินการนี้ไม่ได้เป็นส่วนหนึ่งของ API สาธารณะ โทเค็น OAuth จึงเรียกใช้ไม่ได้ | ใช้การดำเนินการจาก เอกสารอ้างอิง API |
403 org.suspended | องค์กรถูกระงับการใช้งาน ข้อมูลยังคงเก็บไว้ | ติดต่อผู้ดูแลระบบขององค์กร |
403 หมายความว่าคำขอยืนยันตัวตนสำเร็จแต่ไม่ได้รับอนุญาต ออบเจ็กต์ที่คีย์ไม่มีสิทธิ์มองเห็นจะได้การตอบกลับ 404 เหมือนออบเจ็กต์ที่ไม่มีอยู่ คีย์จึงไม่สามารถรู้ได้ว่ามีอะไรอยู่นอกสิทธิ์เข้าถึงของตน
การทำงานในนามของโปรไฟล์ข้อมูล
คีย์ที่มีบทบาท admin ตรวจดูได้ว่าคนอีกกลุ่มหนึ่งจะเห็นอะไร โดยเฮดเดอร์ X-View-As จะรันคำขอในนามของโปรไฟล์ข้อมูล และจะระบุบทบาทด้วยก็ได้
curl "https://api.sursa.com/v1/cards?limit=20" \
-H "Authorization: Bearer $SURSA_ADMIN_KEY" \
-H "X-View-As: employee:viewer"คำขอในโหมดนี้อ่านได้อย่างเดียว การเปลี่ยนแปลงใดก็ตามจะได้การตอบกลับ 403 พร้อมรหัส view_as.read_only โทเค็น OAuth หรือคีย์ที่ไม่มีบทบาท admin ใช้ X-View-As ไม่ได้ และจะได้การตอบกลับ 403 พร้อมรหัส view_as.admin_key_required ส่วนเฮดเดอร์ที่ไม่ได้ระบุโปรไฟล์ที่มีอยู่จริงจะได้การตอบกลับ 400 พร้อมรหัส view_as.invalid_header
แอปพลิเคชันในเบราว์เซอร์
API อนุญาตคำขอจากทุกออริจินของเว็บ (Access-Control-Allow-Origin: *) และไม่ใช้คุกกี้เลย หน้าเว็บจึงเรียก API ด้วย fetch ได้ แต่คีย์จะอยู่ในหน้าเว็บและทุกคนที่ใช้หน้านั้นมองเห็นได้ ให้เรียก API จากเบราว์เซอร์ด้วยคีย์ที่คุณยอมให้ผู้ใช้เหล่านั้นเห็นเท่านั้น เช่น คีย์ viewer ที่จำกัดไว้เฉพาะคอลเลกชันสาธารณะ หรือวางเซิร์ฟเวอร์ของคุณเองไว้ระหว่างเบราว์เซอร์กับ Sursa
สิ่งที่เฉพาะพนักงานเท่านั้นทำได้
คีย์ API ขององค์กรทำงานในนามขององค์กร ไม่ใช่ในนามของบุคคล API มีสองส่วนที่เป็นของบุคคล จึงใช้ได้เฉพาะกับโทเค็นที่ทำงานในนามของพนักงาน ได้แก่ เซสชันใน Sursa หรือโทเค็นเข้าถึง OAuth ที่ออกโดยได้รับความยินยอมจากพนักงาน
บทสนทนาเป็นของบุคคล คีย์ API ขององค์กรเห็นใน GET /v1/conversations เฉพาะบทสนทนาที่คีย์นั้นเริ่มเอง API สาธารณะไม่มีการดำเนินการที่เริ่มบทสนทนา รายการนี้ของคีย์จึงมักว่างเปล่า และคีย์จะไม่เห็นบทสนทนาของพนักงานเลย คำถามที่ไม่อยู่ในบทสนทนาผ่าน POST /v1/ask หรือ POST /v1/chat ใช้ได้กับทุกคีย์ที่มีขอบเขตสิทธิ์ ask หากต้องการแสดงรายการบทสนทนาของพนักงานและอ่านประวัติของบทสนทนาหนึ่งด้วย GET /v1/conversations/{conv_id} ให้เรียก API ด้วยโทเค็น OAuth ในนามของพนักงานคนนั้น โทเค็นจะเห็นเฉพาะบทสนทนาของพนักงานคนนั้นเอง บทสนทนาอื่นจะได้การตอบกลับ 404 พร้อมรหัส conversations.not_found
เฉพาะพนักงานเท่านั้นที่ตรวจสอบการ์ดได้ การตรวจสอบยืนยันว่าบุคคลได้ตรวจเนื้อหาแล้ว POST /v1/cards/{card_id}/verification/verify และ POST /v1/cards/{card_id}/verify จึงต้องใช้เซสชันหรือโทเค็น OAuth ในนามของพนักงานที่มีสิทธิ์ตรวจสอบการ์ดนั้น หากใช้คีย์ API ขององค์กรหรือโทเค็น client_credentials จะได้การตอบกลับ 400 พร้อมรหัส cards.verify_user_account_required การตรวจตามปกติจะทำก่อน การ์ดที่คีย์มองไม่เห็นจะได้การตอบกลับ 404 และคีย์ที่ไม่มีสิทธิ์ตรวจสอบการ์ดนั้นจะได้การตอบกลับ 403