ข้ามไปยังเนื้อหา
Sursa Developers

ขอบเขตสิทธิ์ของคีย์

ขอบเขตสิทธิ์ระบุส่วนของ API ที่คีย์เรียกใช้ได้ ทุกเอนด์พอยต์ใน เอกสารอ้างอิง API ประกาศขอบเขตสิทธิ์ที่ต้องใช้หนึ่งรายการ คำขอที่ใช้คีย์ซึ่งไม่มีขอบเขตสิทธิ์นั้นจะถูกปฏิเสธด้วย 403 และรหัส api_keys.scope ก่อนที่จะมีการอ่านหรือเปลี่ยนแปลงสิ่งใด

ขอบเขตสิทธิ์บอกว่าคีย์เรียกการดำเนินการใดได้ ส่วนบทบาท โปรไฟล์ข้อมูล และคอลเลกชันของคีย์ยังคงเป็นตัวกำหนดว่าการดำเนินการเหล่านั้นมองเห็นออบเจ็กต์ใด คีย์ที่มี cards:write และบทบาท viewer เปลี่ยนแปลงการ์ดไม่ได้ และคีย์ที่จำกัดไว้ที่คอลเลกชันเดียวจะมองไม่เห็นคอลเลกชันอื่น

ขอบเขตสิทธิ์

ขอบเขตสิทธิ์อนุญาต
cards:readอ่านการ์ด คอลเลกชัน และโฟลเดอร์
cards:writeสร้าง เปลี่ยนแปลง และลบการ์ด คอลเลกชัน และโฟลเดอร์
searchค้นหาในฐานความรู้ (POST /v1/search)
askถามผู้ช่วย (POST /v1/ask และ POST /v1/chat)
import:writeเขียนข้อมูลลงในแหล่งข้อมูลแบบกำหนดเองขององค์กร ได้แก่ การซิงก์ ชุด และการลบ และอ่านสถานะของสิ่งเหล่านี้ การสร้างแหล่งข้อมูลและคีย์ของแหล่งข้อมูลต้องใช้ admin
webhooks:manageจัดการเว็บฮุกและอ่านฟีดอีเวนต์ (GET /v1/webhook-events) ทั้งสองอย่างต้องมีบทบาท admin ด้วย
users:readอ่านผู้ใช้และกลุ่ม
users:writeเปลี่ยนแปลงผู้ใช้และกลุ่ม
analytics:readอ่านข้อมูลการวิเคราะห์
audit:readอ่านล็อกการตรวจสอบ
finance:readอ่านรายงานทางการเงิน ใบแจ้งหนี้ และการชำระเงิน
catalog:readอ่านแค็ตตาล็อกบริการ
files:readอ่านไฟล์ที่ระบบสร้างขึ้น เช่น คำตอบที่ส่งออก
files:writeเปลี่ยนแปลงและลบไฟล์ที่ระบบสร้างขึ้น
permissions:manageให้และเพิกถอนสิทธิ์ในออบเจ็กต์
adminการตั้งค่าขององค์กรและคีย์ API ขององค์กร คีย์ที่มี admin จะมีขอบเขตสิทธิ์อื่นทั้งหมดด้วย

การค้นหาและการถามคำถามนับเป็นการอ่าน คีย์ที่อ่านได้อย่างเดียวจึงยังค้นหาและถามได้

การเลือกขอบเขตสิทธิ์

ให้เฉพาะขอบเขตสิทธิ์ที่ระบบที่เชื่อมต่อใช้งานจริง และไม่ให้มากกว่านั้น:

ระบบที่เชื่อมต่อขอบเขตสิทธิ์
บอตถาม-ตอบในเครื่องมือแชตsearch และ ask
นำเข้าจากระบบจัดการเอกสารของคุณcards:write (API การ์ด) หรือ import:write (แหล่งข้อมูลแบบกำหนดเอง)
ส่งออกไปยังคลังข้อมูลcards:read users:read และ webhooks:manage สำหรับฟีดอีเวนต์
สร้างบัญชีผู้ใช้จากระบบ HR ของคุณusers:write

ส่งรายการขอบเขตสิทธิ์เมื่อสร้างคีย์:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Support bot", "role": "viewer", "scopes": ["search", "ask"]}'

ขอบเขตสิทธิ์แบบเดิม

คีย์ที่สร้างขึ้นก่อนการแยกขอบเขตสิทธิ์ยังใช้งานได้ตามปกติ ขอบเขตสิทธิ์ read write และ admin ของคีย์เหล่านี้หมายถึงชุดต่อไปนี้:

ขอบเขตสิทธิ์แบบเดิมความหมาย
readcards:read search ask users:read analytics:read finance:read catalog:read และ files:read
writeทุกอย่างใน read รวมถึง cards:write files:write users:write และ permissions:manage
adminทุกขอบเขตสิทธิ์

คีย์ที่สร้างโดยไม่ระบุขอบเขตสิทธิ์จะได้ขอบเขตสิทธิ์ตามบทบาท: admin ได้ admin ส่วน editor และ verifier ได้ write และ viewer ได้ read

ดูขอบเขตสิทธิ์ของคีย์

GET /v1/me ส่งคืนขอบเขตสิทธิ์ของคีย์ที่ส่งคำขอ ไม่ว่าคีย์นั้นจะมีขอบเขตสิทธิ์แบบใด สำหรับคีย์ที่สร้างโดยไม่ได้ระบุขอบเขตสิทธิ์ ค่าเหล่านี้คือขอบเขตสิทธิ์แบบเดิมของบทบาท เช่น read และ write ตารางด้านบนแสดงว่าแต่ละค่าหมายถึงอะไร เมื่อการดำเนินการล้มเหลวด้วย api_keys.scope ฟิลด์ error.message จะระบุขอบเขตสิทธิ์ที่ขาดไป