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

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

v1.13.0

ทุกคำขอไปยัง public API (/api/v1/...) ต้องยืนยันตัวตนด้วย API key คีย์จะถูกออกและจัดการจากแดชบอร์ด — ตัว public API เองไม่มี endpoint สำหรับจัดการคีย์ ดังนั้นคีย์หนึ่งจึงไม่สามารถถูกใช้เพื่อสร้างหรือเพิกถอนคีย์อื่นได้

การสร้างคีย์

1. ไปที่ ตั้งค่าองค์กร (Organization Settings) → API Keys

2. คลิก Create Key ตั้งชื่อ และเลือกขอบเขตสิทธิ์ (scopes) หนึ่งรายการขึ้นไป ดูรายการทั้งหมดได้ที่หัวข้อ ขอบเขตสิทธิ์ ด้านล่าง ฟอร์มนี้จะออกคีย์แบบ live — สำหรับคีย์แบบ sandbox ดูที่ Sandbox ซึ่งใช้การเรียก provisioning แยกต่างหาก

3. คัดลอก secret ที่แสดงในหน้าต่างนั้น นี่คือครั้งเดียวที่คีย์เต็มจะถูกแสดง — หลังจากนั้นแดชบอร์ดจะเก็บและแสดงเพียง lastFour แบบตัดทอนเท่านั้น

Secret แสดงครั้งเดียว

โทเคนเต็มจะถูกส่งกลับเพียงครั้งเดียว ในเนื้อหาการตอบกลับของคำขอสร้างคีย์ Clienta.ai ไม่เคยเก็บหรือบันทึก secret ในรูปแบบที่กู้คืนได้ — จะเก็บเพียงค่า digest แบบ HMAC เท่านั้น หากคุณทำ secret หาย ให้เพิกถอนคีย์นั้นแล้วสร้างคีย์ใหม่

รูปแบบคีย์

ck_{environment}_{keyId}.{secret}

• environment คือ live หรือ sandbox
• keyId เป็นสตริง base64url ยาว 22 ตัวอักษร (สุ่ม 128-bit)
• secret เป็นสตริง base64url ยาว 43 ตัวอักษร (สุ่ม 256-bit) คั่นจาก keyId ด้วยเครื่องหมาย .

ตัวอย่าง: ck_live_8f2N3q...Ab.9xQ1z...pR

ส่งเป็น bearer token มาตรฐาน:

Authorization: Bearer ck_live_8f2N3qkYV2b1jH0mQe4xAb.9xQ1zPr7wLskFn2VmY0aRcTdEjHlBpR

โทเคนที่ไม่ตรงกับรูปแบบนี้จะถูกปฏิเสธด้วย 401 Unauthorized ก่อนที่จะมีการค้นหาในฐานข้อมูลใดๆ — โทเคนที่ผิดรูปแบบจึงไม่เสียเวลา round trip และถูกนับแยกจากคีย์ที่ไม่ถูกต้อง/ถูกเพิกถอนจริงๆ ในเมตริกการตรวจจับการโจมตีของเรา

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

คีย์ทุกอันจะถูกออกพร้อมขอบเขตสิทธิ์อย่างน้อยหนึ่งรายการ คำขอที่ route ต้องการ scope ที่คีย์ไม่มี จะถูกปฏิเสธด้วย 403 INSUFFICIENT_SCOPE

Scope	ให้สิทธิ์
read:conversations	อ่านบทสนทนาและข้อความ
read:contacts	อ่านรายชื่อผู้ติดต่อ
read:analytics	อ่านข้อมูลวิเคราะห์
read:channels	อ่านการตั้งค่าช่องทาง
read:kb	อ่านเอกสารในคลังความรู้
write:kb	อัปโหลดเอกสารในคลังความรู้
read:webhooks	แสดงรายการ webhook endpoint และประวัติการส่ง
write:webhooks	สร้าง ลบ และทดสอบ webhook endpoint

API นี้เป็นแบบ default-deny: ทุก route ภายใต้ /api/v1 ต้องประกาศ scope ที่ต้องการอย่างชัดเจน มิฉะนั้นเซิร์ฟเวอร์จะตอบกลับ 500 ROUTE_MISCONFIGURED แทนที่จะปล่อยให้คำขอผ่านไปโดยไม่ตั้งใจ

Tip

ให้คีย์มีเฉพาะ scope ที่จำเป็นเท่านั้น การเชื่อมต่อแบบอ่านอย่างเดียวไม่ควรมี scope ประเภท write:*

Environment: live กับ sandbox

คีย์ live ทำงานกับข้อมูลจริงขององค์กรของคุณ ส่วนคีย์ sandbox จะถูกส่งต่อไปยังองค์กร sandbox ที่จับคู่ไว้ซึ่งมีข้อมูลแยกต่างหากโดยอัตโนมัติ — ดูรายละเอียดทั้งหมดได้ที่ Sandbox คีย์ sandbox จะใช้ระดับ rate-limit ต่ำสุดเสมอ ไม่ว่าแพ็กเกจของคุณจะเป็นอะไรก็ตาม

วันหมดอายุ

คุณสามารถกำหนดวันที่ expiresAt เมื่อสร้างคีย์ได้ (ไม่บังคับ) คีย์ที่หมดอายุจะล้มเหลวในการยืนยันตัวตนเช่นเดียวกับคีย์ที่ถูกเพิกถอน — คือ 401 Unauthorized — แม้ว่าจะไม่มีใครเพิกถอนคีย์นั้นด้วยตนเองก็ตาม

การหมุนเวียนคีย์ (Rotation)

ไม่มีการ “หมุนเวียน” แบบแก้ไขคีย์เดิมในที่เดียว — secret ของคีย์ไม่สามารถเปลี่ยนได้โดยไม่เปลี่ยนตัวตนของคีย์ วิธีหมุนเวียนคีย์โดยไม่มีดาวน์ไทม์:

1. สร้าง คีย์ใหม่ ด้วย scope และ environment เดียวกันกับคีย์ที่กำลังจะหมุนเวียน

2. นำคีย์ใหม่ไปใช้กับระบบของคุณและยืนยันว่าใช้งานได้

3. เพิกถอน คีย์เก่าจาก ตั้งค่าองค์กร → API Keys

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

การเพิกถอน

การเพิกถอนคีย์มีผลทันทีและเป็นแบบ fail-closed: คำขอถัดไปที่ใช้คีย์นั้นจะถูกปฏิเสธด้วย 401 Unauthorized ทันที แม้จะเกิดข้อผิดพลาดระหว่างการตรวจสอบสถานะเพิกถอนในฝั่งเรา (ความล้มเหลวในการค้นหาจะไม่ตกกลับไปเป็น “อนุญาต” โดยอัตโนมัติ)

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

สิ่งที่เราไม่บันทึกเด็ดขาด

• Secret ที่เป็นข้อความล้วน (plaintext) — จะเก็บเพียงค่า digest แบบ HMAC-SHA256 (โดยใช้ pepper ฝั่งเซิร์ฟเวอร์ที่มีเวอร์ชัน)
• ค่าของ header Authorization ในบันทึก log ใดๆ ที่ระดับใดก็ตาม

การหมุนเวียนกุญแจภายในระบบ

Pepper ที่ Clienta.ai ใช้แฮช secret ของคีย์ที่เก็บไว้ และกุญแจเข้ารหัสแบบ envelope ที่ใช้กับ secret สำหรับเซ็น webhook จะถูกหมุนเวียนแยกจากคีย์ API ของคุณ และไม่ต้องดำเนินการใดๆ จากฝั่งคุณ — คีย์ที่มีอยู่ยังคงใช้งานได้ต่อเนื่องแม้จะมีการหมุนเวียน pepper ดูวิธีที่สิ่งนี้ส่งผลต่อการตรวจสอบลายเซ็น webhook โดยเฉพาะได้ที่ คู่มือการตรวจสอบลายเซ็น Webhook → การหมุนเวียน Secret