คีย์ API และขอบเขตสิทธิ์

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

สิ่งที่คีย์ได้รับอนุญาตให้ทำ

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

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

ให้แต่ละระบบที่เชื่อมต่อมีคีย์ของตัวเองซึ่งมีบทบาทและขอบเขตสิทธิ์แคบที่สุดเท่าที่จำเป็น งานซิงก์ที่เขียนเอกสารอย่างเดียวไม่ต้องใช้ admin และงานออกรายงานไม่ต้องใช้ขอบเขตสิทธิ์สำหรับเขียน

สร้างคีย์

ผู้ดูแลระบบขององค์กรสร้างคีย์ได้ใน Sursa ที่ Administration → API keys (การดูแลระบบ → คีย์ API) หรือด้วย POST /v1/api-keys โดยใช้คีย์หรือเซสชันที่มีบทบาท admin:

curl -X POST https://api.sursa.com/v1/api-keys \
  -H "Authorization: Bearer $SURSA_ADMIN_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "CRM sync",
    "role": "editor",
    "expires_at": "2027-06-30T00:00:00Z"
  }'

การตอบกลับมีค่าของคีย์อยู่ใน key ค่านี้แสดง ครั้งเดียว เท่านั้น Sursa เก็บไว้เพียงค่าแฮชของคีย์และแสดงคีย์ซ้ำไม่ได้ คีย์มีลักษณะเป็น kb_ ตามด้วยอักขระ 43 ตัว อักขระช่วงแรก (prefix) แสดงในรายการคีย์เพื่อให้คุณแยกคีย์แต่ละคีย์ออกจากกันได้

หากไม่ระบุ scopes คีย์จะได้ขอบเขตสิทธิ์ตามบทบาท ส่ง scopes เพื่อจำกัดให้แคบลงอีก หากไม่ระบุ expires_at คีย์จะไม่หมดอายุ

เก็บคีย์เป็นความลับ

• เก็บคีย์ไว้ในระบบจัดการข้อมูลลับหรือในตัวแปรสภาพแวดล้อมของบริการของคุณ ห้ามเก็บไว้ในซอร์สโค้ด
• ใช้คีย์จากเซิร์ฟเวอร์ของคุณเท่านั้น Sursa รับคำขอจากเบราว์เซอร์ได้ (CORS เปิดอยู่) แต่คีย์ที่อยู่ในหน้าเว็บจะมองเห็นได้โดยทุกคนที่เปิดหน้านั้น
• ห้ามส่งคีย์ใน URL ให้ส่งในเฮดเดอร์ Authorization เท่านั้น
• หากคีย์รั่วไหล ให้เพิกถอนทันทีและสร้างคีย์ใหม่

ตรวจสอบคีย์

GET /v1/me ส่งคืนคีย์ บทบาท ขอบเขตสิทธิ์ที่มีผลจริง โปรไฟล์ข้อมูล วันหมดอายุ และขีดจำกัดอัตราการเรียกของคีย์ เอนด์พอยต์นี้ใช้ได้กับทุกคีย์ที่ใช้งานได้ ไม่ว่าคีย์จะมีขอบเขตสิทธิ์ใด จึงเหมาะสำหรับทดสอบการเชื่อมต่อของระบบที่เชื่อมต่อ และใช้ตรวจหาสาเหตุเมื่อได้ 403

หมุนเวียนคีย์

การหมุนเวียนคือการเปลี่ยนคีย์ใหม่โดยไม่ต้องหยุดระบบที่เชื่อมต่อ วิธีที่เร็วที่สุดคือออกค่าใหม่ให้คีย์ POST /v1/api-keys/{key_id}/roll ออกค่าใหม่ให้คีย์เดิมโดยคงบทบาท ขอบเขตสิทธิ์ คอลเลกชัน และวันหมดอายุไว้เหมือนเดิม ค่าเดิมยังใช้ได้ต่อไปตลอด overlap_hours (ค่าเริ่มต้น 24 ชั่วโมง สูงสุด 168 ชั่วโมง) คุณจึงนำค่าใหม่ไปใช้งานได้ในช่วงนั้น ส่วน POST /v1/api-keys/{key_id}/revoke-previous จะสิ้นสุดช่วงเปลี่ยนผ่านก่อนกำหนด

หากต้องการเปลี่ยนเป็นคีย์อื่นแทน:

1. สร้างคีย์ใหม่ที่มีบทบาท ขอบเขตสิทธิ์ และโปรไฟล์ข้อมูลเหมือนเดิม
2. นำคีย์ใหม่ไปใช้ในระบบที่เชื่อมต่อ
3. เฝ้าดูคีย์เดิมใน Administration → API keys (หรือ last_used ใน GET /v1/api-keys) จนกว่าจะไม่มีการใช้งานแล้ว
4. เพิกถอนคีย์เดิม

กำหนดวันหมดอายุให้คีย์และหมุนเวียนคีย์ก่อนถึงวันนั้น Sursa แจ้งเตือนผู้ดูแลระบบขององค์กรก่อนคีย์หมดอายุ คีย์ที่หมดอายุแล้วจะได้การตอบกลับ 401 พร้อมรหัส api_keys.expired

เพิกถอนคีย์

เพิกถอนคีย์ได้ที่ Administration → API keys หรือด้วย DELETE /v1/api-keys/{key_id} การเพิกถอนมีผลภายในไม่กี่วินาทีบนเซิร์ฟเวอร์ API ทุกเครื่อง คำขอที่ใช้คีย์ที่ถูกเพิกถอนจะได้การตอบกลับ 401 พร้อมรหัส auth.not_authenticated

คีย์ของแหล่งข้อมูลแบบกำหนดเอง

แหล่งข้อมูลแบบกำหนดเอง มีคีย์ประเภทของตัวเอง คีย์นี้ขึ้นต้นด้วย kbsrc_ เขียนเอกสารได้เฉพาะในแหล่งข้อมูลนั้นแหล่งเดียว และอ่านหรือค้นหาสิ่งใดไม่ได้ จึงเป็นคีย์ที่ปลอดภัยที่สุดสำหรับมอบให้แพลตฟอร์มเชื่อมต่อระบบอย่าง Zapier สร้างคีย์นี้ได้ในหน้าแหล่งข้อมูลที่ส่วน API keys (คีย์ API) หรือด้วย POST /v1/sources/{source_id}/push-keys

เมื่อใช้คีย์ไม่ได้

คีย์ API เป็นส่วนหนึ่งของแพ็กเกจขององค์กร หากแพ็กเกจไม่รวมคีย์ API การสร้างคีย์และทุกคำขอที่ใช้คีย์จะได้การตอบกลับ 403 พร้อมรหัส api_keys.feature_disabled