← บทความทั้งหมด
บทช่วยสอน

วิธีหมุนเวียน UnifyPort API Key โดยระบบไม่หยุดทำงาน

หากต้องการเปลี่ยน UnifyPort API Key โดยระบบไม่หยุดทำงาน อย่าเริ่มด้วย rotate endpoint เพราะเมื่อ POST /v1/api-keys/{key_id}/rotate สำเร็จ คีย์เดิมจะใช้ไม่ได้ทันที วิธีที่ปลอดภัยคือสร้างคีย์ที่สอง เก็บ secret ใหม่ซึ่งแสดงเพียงครั้งเดียว นำไปใช้กับทุก service ทดสอบด้วย GET /v1/workspace แล้วจึงเปลี่ยนคีย์เดิมเป็น inactive

สรุปสำคัญ

  • rotate endpoint เป็นการตัดสลับทันที ไม่มีช่วงผ่อนผันให้คีย์เดิม
  • การเปลี่ยนแบบไม่หยุดระบบต้องมีคีย์ active สองชุดชั่วคราว ตามลำดับ สร้าง นำขึ้นระบบ ตรวจสอบ และปิดคีย์เดิม
  • secret แบบเต็มจะแสดงใน data.api_key เพียงครั้งเดียว และเรียกดูภายหลังไม่ได้
  • รายการคีย์แสดงเฉพาะ metadata เช่น key_prefix และสถานะ
  • ใช้วิธีสร้างแล้วปิดคีย์เดิมสำหรับ rolling deployment ปกติ และใช้ rotate เมื่อต้องเพิกถอนคีย์เดิมทันทีจริง ๆ

ทำไมเรียก rotate ก่อนแล้ว production อาจสะดุด

เอกสาร Rotate API key ระบุ operation นี้อย่างชัดเจน:

POST /v1/api-keys/{key_id}/rotate

ระบบจะสร้าง key record ใหม่และส่ง secret ใหม่กลับมาเพียงครั้งเดียว พร้อมทำให้คีย์เดิมใช้ไม่ได้ทันที พฤติกรรมนี้เหมาะเมื่อ credential เดิมอาจรั่วไหล แต่เสี่ยงหาก web process, queue worker, scheduled job หรือ instance ในอีก region ยังอ่านค่าเดิมอยู่ เพราะคำขอเหล่านั้นอาจได้รับ 401 invalid_api_key

rolling deployment ต้องมีช่วงที่ config ใหม่และเก่าทำงานคู่กันชั่วคราวอยู่แล้ว การเปลี่ยน credential แบบทันทีจะตัดช่วงซ้อนทับนี้ออก แม้ application ปกติก็เกิด authentication error ได้

NIST SP 800-53 กล่าวถึงแนวคิดทั่วไปในการเปลี่ยนหรืออัปเดต authenticator ภายใต้การจัดการ authenticator แต่ลำดับการปฏิบัติจริงต้องอิง contract ของผลิตภัณฑ์ UnifyPort รองรับ API key record หลายรายการ ส่วน rotate จะยกเลิกคีย์เดิมทันที

Runbook การเปลี่ยน API Key แบบไม่หยุดระบบ

1. สำรวจทุกจุดที่เรียก API

ทำรายการทุก component ที่ส่ง X-Api-Key ไปยัง https://api.unifyport.ai ได้แก่ public API, background worker, งาน webhook ที่เรียกตอบข้อความ, scheduled job, เครื่องมือ production และ health check

API Key ไม่ใช่ signing_secret ของ webhook โดย API Key ใช้ยืนยันคำขอจากระบบของคุณไปยัง UnifyPort REST API ส่วน signing_secret ใช้ตรวจสอบ webhook ที่ UnifyPort ส่งเข้ามา อ่านรายละเอียดของ secret แบบหลังได้ในคู่มือ Webhook HMAC การป้องกันการส่งซ้ำ และ retry

ตรวจสอบ record ปัจจุบันด้วย List API keys:

curl https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY"

response ให้ id, name, key_prefix และ status แต่ไม่เปิดเผย secret แบบเต็ม

2. สร้างคีย์ active ชุดที่สอง

ใช้ Create API key แทน rotate:

curl -X POST https://api.unifyport.ai/v1/api-keys \
  -H "X-Api-Key: $CURRENT_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production 2026-08 cutover",
    "prefix": "dk_live"
  }'

เมื่อสำเร็จ response 201 จะคืน metadata ใน data.key และ secret ใหม่แบบเต็มใน data.api_key เพียงครั้งเดียว บันทึกค่าเข้าระบบจัดการ secret ที่ทีมอนุมัติโดยตรง ห้ามพิมพ์ลง deployment log, ticket หรือแชต

ถ้าค่าครั้งเดียวหายไปก่อน deploy ให้สร้างคีย์ใหม่อีกชุดแล้วปิด record ที่ไม่ได้ใช้ ไม่สามารถกู้ secret จาก prefix ได้

3. พิสูจน์ว่าคีย์ใหม่ใช้ได้ก่อน deploy

ใช้ secret ใหม่กับคำขอแบบ read-only:

curl https://api.unifyport.ai/v1/workspace \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY"

response ที่สำเร็จยืนยันว่าคีย์ใหม่เชื่อมกับ workspace ได้ แต่ยังไม่ยืนยันว่าทุก instance โหลดค่าใหม่แล้ว จากนั้นอัปเดต secret reference ของ deployment และทยอยปล่อยไปยัง caller แต่ละประเภท โดยคงคีย์เดิมเป็น active ระหว่างช่วงนี้

สำหรับทีมไทยที่ใช้ LINE เป็นช่องทางหลัก อย่าตรวจเฉพาะ LINE handler ต้องรวม worker กลางที่ดูแล WhatsApp, Telegram หรือช่องทางอื่น งานตอบข้อความ และ scheduled job ด้วย

4. ตรวจสอบทั้งระบบว่าใช้ credential ใหม่

ก่อนปิดคีย์เดิม ให้ตรวจว่า:

  • web และ API instance deploy ครบแล้ว
  • queue consumer restart หรือ reload config แล้ว
  • scheduled job จะอ่าน secret ใหม่ในการรันครั้งถัดไป
  • เส้นทางส่งหรือตอบข้อความเรียก authenticated request ได้
  • ไม่มี emergency script ใช้ค่าเก่าที่คัดลอกไว้ในเครื่อง

ใช้ผลลัพธ์คำขอจาก application และสถานะ deployment เป็นหลัก รายการคีย์ของ UnifyPort แสดง metadata และสถานะ แต่ไม่ได้ระบุ field สำหรับเวลาที่แต่ละคีย์ถูกใช้ล่าสุด จึงไม่ควรสรุปจากข้อมูลที่ endpoint ไม่ได้ส่งคืน

หากทีมเริ่มจาก dashboard สามารถอ่านประกาศ dashboard และการจัดการ API Keyเพื่อเข้าใจ workflow โดยรวม ส่วนบทความนี้เติมลำดับ deployment สำหรับระบบที่กำลังให้บริการ

5. ปิดใช้งานคีย์เดิม

เมื่อยืนยันว่าทุก caller ใช้ secret ใหม่แล้ว ให้ใช้คีย์ใหม่เรียก Update API key status:

curl -X PATCH "https://api.unifyport.ai/v1/api-keys/$OLD_KEY_ID" \
  -H "X-Api-Key: $NEW_UNIFYPORT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"status":"inactive"}'

สถานะที่เอกสารรองรับคือ active และ inactive หลังปิดแล้ว ให้ใช้คีย์เก่าทำคำขอ read-only ที่ควบคุมไว้หนึ่งครั้ง และยืนยันว่าได้ 401 invalid_api_key อย่าใช้งานลูกค้าจริงเป็นตัวทดสอบ

สุดท้าย ลบค่าเก่าออกจาก deployment config, local environment file, CI variable และไฟล์ชั่วคราว เก็บเฉพาะข้อมูลที่ไม่เป็นความลับ เช่น key ID, ชื่อ, สถานะ, ผู้รับผิดชอบ และเวลา cutover

เมื่อใดควรใช้ rotate แบบทันที

ใช้ POST /v1/api-keys/{key_id}/rotate เมื่อการทำให้ credential เดิมใช้ไม่ได้ทันทีเป็นข้อกำหนด เช่น สงสัยว่าคีย์ถูกเปิดเผย หรือมี maintenance window ที่ caller ทั้งหมดเปลี่ยนพร้อมกันได้

ลำดับในกรณีนี้คือ:

  1. หยุดหรือแยก caller ที่ยังถือคีย์เดิม
  2. เรียก rotate จากเส้นทาง operator ที่ควบคุมได้
  3. เก็บ data.api_key ซึ่งแสดงครั้งเดียว
  4. อัปเดต secret consumer ทั้งหมด
  5. เปิด traffic และตรวจ authentication

วิธีนี้ให้ความสำคัญกับความเร็วในการเพิกถอนมากกว่าความต่อเนื่องของบริการ หากสงสัยว่า credential รั่วไหล ไม่ควรยืดช่วงที่คีย์สองชุด active เพียงเพื่อรักษา traffic แต่ควรทำตามนโยบาย incident ของทีม

ข้อจำกัดและสิ่งที่ต้องแลก

ช่วงที่มีคีย์สองชุดหมายความว่า credential ทั้งคู่เข้าถึง workspace ได้ ควรทำช่วงนี้ให้สั้นและจำกัดผู้ที่อ่าน secret ได้ เอกสาร introduction ของ UnifyPort ระบุว่า X-Api-Key ชี้ไปยัง workspace หนึ่งแห่งและให้สิทธิ์ภายใน workspace จึงไม่ใช่การย้ายสิทธิ์แยกตาม endpoint

runbook นี้ไม่เปลี่ยน webhook signing_secret, credential สำหรับล็อกอินแพลตฟอร์ม หรือ imported session เพราะ secret แต่ละประเภทมี consumer และรูปแบบความเสียหายต่างกัน ควรเปลี่ยนและทดสอบแยกกัน

FAQ

UnifyPort API Key rotation มี grace period หรือไม่?

rotate endpoint ที่ระบุในเอกสารไม่มี grace period คีย์เดิมใช้ไม่ได้ทันทีเมื่อสำเร็จ หากต้องการช่วงซ้อนทับ ให้สร้างคีย์ที่สองก่อน

เรียกดู API Key ใหม่ภายหลังได้หรือไม่?

ไม่ได้ ค่าฉบับเต็มแสดงใน data.api_key เพียงครั้งเดียว รายการภายหลังแสดงเฉพาะ prefix และสถานะ

ทดสอบคีย์ใหม่อย่างปลอดภัยอย่างไร?

เรียก GET /v1/workspace ด้วย X-Api-Key ใหม่ แล้วตรวจว่าทุก caller ที่ deploy แล้วโหลด secret เดียวกันก่อนปิดคีย์เดิม

ควรใช้ rotate หรือสร้างแล้วปิดคีย์เดิม?

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

API Key เหมือนกับ signing_secret หรือไม่?

ไม่เหมือนกัน X-Api-Key ยืนยันคำขอ REST API ส่วน signing_secret ใช้ตรวจลายเซ็น HMAC-SHA256 ของ webhook

ขั้นตอนถัดไป

เปิด Create API key reference สร้าง production credential คู่ขนาน และผ่านจุดตรวจทั้งห้าข้อก่อนเปลี่ยนสถานะคีย์เดิม

แหล่งข้อมูล

ตรวจสอบเมื่อ 17 สิงหาคม 2026