API keys และ scopes

ตำแหน่งในพอร์ทัล: API keys (/api-keys). ตำแหน่งในหน้าผู้ดูแลระบบ: Customers › Customers › API keys (/customers/apikeys)

What it does

API key ช่วยให้สคริปต์, งาน CI, cmp CLI หรือผู้ช่วย AI (MCP) สามารถเรียก REST API ในนามของลูกค้าคนใดคนหนึ่งได้ โดยมีเฉพาะสิทธิ์ (scopes) ที่ได้รับอนุญาตเท่านั้น คีย์ของลูกค้าจะขึ้นต้นด้วย vk_ สามารถอ่านและจัดการบริการได้แต่ ไม่สามารถ แตะต้องเรื่องเงินหรือตัวบัญชีได้

ข้อกำหนด

Item	Requirement
ลูกค้า	เซสชันพอร์ทัลที่เข้าสู่ระบบแล้ว (คีย์ไม่สามารถสร้างหรือแก้ไขคีย์อื่นได้ และผู้ดูแลระบบที่สวมรอยเป็นลูกค้าก็ทำไม่ได้เช่นกัน)
สวิตช์	API keys ถูกเปิดใช้งานเป็นค่าเริ่มต้น หากปิดใช้งาน การเรียกใช้งานจะตอบกลับด้วย 401 api_keys_disabled
Dependencies	สิทธิ์การใช้งาน (Scopes) ของผลิตภัณฑ์จะปรากฏขึ้นเมื่อผลิตภัณฑ์นั้นเปิดใช้งานบนเว็บไซต์แล้วเท่านั้น

สร้างคีย์ (สำหรับลูกค้า)

1. ลงชื่อเข้าใช้พอร์ทัลและเปิด API keys

2. คลิก Create key

3. กรอกข้อมูลในฟอร์ม:

   ฟิลด์	กฎ
   Key name	จำเป็นต้องกรอก ความยาวสูงสุด 60 ตัวอักษร ("deploy server", "backup script")
   สิ่งที่คีย์นี้ทำได้	ทำเครื่องหมายเลือกสิทธิ์ที่ต้องการอย่างน้อยหนึ่งสิทธิ์ คีย์แบบอ่านอย่างเดียวไม่ควรมีสิทธิ์เขียน โปรดระมัดระวังเกี่ยวกับสิทธิ์ที่มีค่าใช้จ่ายหรือลบข้อมูล
   Expiry	ไม่มีวันหมดอายุ, 30 วัน, 90 วัน หรือ 1 ปี (API รองรับ 1 ถึง 3650 วัน)
   อนุญาตการเรียกเฉพาะจาก IP เหล่านี้	ระบุหนึ่ง IP หรือช่วง CIDR ต่อบรรทัด สูงสุด 20 รายการ (IPv4 หรือ IPv6) หากเว้นว่างหมายถึงอนุญาตทุก IP ควรกำหนด IP ของเซิร์ฟเวอร์คุณไว้เสมอหากทำได้

4. ยืนยันแบบฟอร์ม คีย์จะแสดงขึ้น ครั้งเดียว ในหน้าต่าง "Key created — shown ONCE" คัดลอกเก็บไว้แล้วคลิก I saved the key ระบบจะจัดเก็บเฉพาะแฮช SHA-256 เท่านั้น ดังนั้นแม้แต่ผู้ดูแลระบบก็ไม่สามารถอ่านคีย์นี้ได้อีก หากทำหาย ให้เพิกถอนและสร้างใหม่

5. พอร์ทัลยังแสดงคำสั่ง curl พร้อมใช้งานสำหรับทดสอบคีย์ด้วย

คีย์จะมีลักษณะขึ้นต้นด้วย vk_ ตามด้วยสตริงสุ่มขนาดยาว รายการจะแสดงเฉพาะอักษรตัวแรก (เช่น vk_a1b2c3d4), สิทธิ์ (scopes), วันหมดอายุ, การใช้งานล่าสุด, จำนวนคำขอ และสถานะ (Active, Expired, Revoked)

แก้ไข, เพิกถอน, ตรวจสอบ

• Edit ใช้สำหรับเปลี่ยนชื่อ, ขอบเขต (scopes), IP ที่อนุญาต และวันหมดอายุ ซึ่งไม่อนุญาตให้ทำระหว่างเซสชันที่มีการสวมรอย
• Revoke จะหยุดการทำงานของคีย์ทันทีและไม่สามารถย้อนกลับได้ แถวข้อมูลจะยังคงอยู่เพื่อให้บันทึกการใช้งานยังคงดูได้
• Key usage log แสดงคำสั่งเขียนและข้อผิดพลาดทั้งหมดในช่วง 60 วันที่ผ่านมา ได้แก่ เวลา, คำขอ, คีย์, ผลลัพธ์ และ IP ต้นทาง
• ตามค่าเริ่มต้น บัญชีหนึ่งสามารถถือ 10 active keys ได้มากที่สุด
• คีย์ที่สร้างผ่าน CLI หรือการเข้าสู่ระบบ MCP จะปรากฏภายใต้ Connected apps & devices และสามารถเพิกถอนได้ที่นั่น

Scopes

ชื่อขอบเขตจะมีรูปแบบ area:action โดยขอบเขตที่มีให้บริการจะขึ้นอยู่กับผลิตภัณฑ์ที่คุณเปิดใช้งาน

Scope	Allows
catalog:read	อ่านแผนบริการและแค็ตตาล็อก
vm:read	อ่านข้อมูล VM, เมตริก และใบแจ้งหนี้ของ VM
vm:write	การดำเนินการด้านพลังงาน, การเปลี่ยนแปลงเล็กน้อย, ไฟร์วอลล์, สแนปชอตด่วน
vm:create	สร้าง VMs (มีค่าใช้จ่าย)
vm:plan	เปลี่ยนแผนบริการหรือปรับขนาด (มีค่าใช้จ่าย)
vm:destroy	ลบ VMs
vm:restore	กู้คืน VM จากสแนปชอต (จะเขียนทับดิสก์)
vm:console	เปิดตั๋วคอนโซล VNC
sshkey:read, sshkey:write	อ่าน, เพิ่ม และลบ SSH Keys
volume:read, volume:write, volume:create, volume:destroy	โวลุ่มข้อมูล (การสร้างและขยายมีค่าใช้จ่าย การทำลายทำให้ข้อมูลสูญหาย)
backup:read, backup:write, backup:restore	Backups (การกู้คืนจะเขียนทับดิสก์)
billing:read	กระเป๋าเงิน, ใบแจ้งหนี้, ประวัติการชำระเงิน — อ่านอย่างเดียว
bandwidth:buy	ซื้อแบนด์วิดท์เสริม (มีค่าใช้จ่าย)
account:read, account:write	โปรไฟล์, ภาพรวม, กิจกรรม, การแจ้งเตือน; account:write ทำเครื่องหมายการแจ้งเตือนว่าอ่านแล้วเท่านั้น
apikey:read	แสดงรายการคีย์ของบัญชีและบันทึกการใช้งาน (ไม่สามารถสร้าง, แก้ไข หรือเพิกถอนได้)
apikey:self	มีอยู่โดยปริยายสำหรับทุกคีย์: ตรวจสอบคีย์ที่เรียกใช้งาน (GET /v1/apikeys/self)
ticket:read, ticket:write	ตั๋วสนับสนุน
aff:read, transfer:read	โปรแกรมพันธมิตรและการโอนย้ายบริการ — อ่านอย่างเดียว
k8s:read, k8s:write, k8s:create, k8s:scale, k8s:destroy, k8s:kubeconfig	Kubernetes (การสร้างและการปรับขนาดมีค่าใช้จ่าย; kubeconfig มีสิทธิ์เป็น cluster-admin)
vpc:read, vpc:write, vpc:create, vpc:destroy	Private Cloud
image:read, image:write	อิมเมจ OS และ ISO (การจัดเก็บคิดค่าบริการเป็นรายชั่วโมง)
s3:read, s3:write, s3:create, s3:destroy, s3:keys	Object Storage (คีย์ลับ S3 จะแสดงเพียงครั้งเดียว)
vpn:read, vpn:detail, vpn:write, vpn:create, vpn:destroy	VPN และพร็อกซี IPv6 (รายละเอียดการเชื่อมต่อรวมถึงรหัสผ่านพร็อกซีด้วย)
dedicated:read, dedicated:write, dedicated:console, dedicated:create, dedicated:destroy	เซิร์ฟเวอร์เฉพาะ (สร้างคำสั่งซื้อจากกระเป๋าเงิน การทำลายจะติดตั้ง OS ใหม่)
shield:read, shield:write, shield:agent	DDoS Shield เฉพาะเมื่อเปิดใช้งานโมดูลนั้น

การเรียกใช้งานนอกขอบเขตของคีย์จะตอบกลับด้วย 403 scope_required; เส้นทางที่ไม่มีคีย์ใดได้รับอนุญาตให้เรียกจะตอบกลับด้วย 403 endpoint_not_public

สิ่งที่คีย์ไม่สามารถทำได้เลย

ไม่มีขอบเขตใดที่สามารถทำสิ่งเหล่านี้ได้: การเติมเงินหรือถอนเงิน, การเปลี่ยนบัตรหรือการเติมเงินอัตโนมัติ, การเปลี่ยนรหัสผ่าน, อีเมล หรือ 2FA, การลบบัญชี, การสร้าง, แก้ไข หรือเพิกถอนคีย์อื่น ๆ สิ่งเหล่านี้จำเป็นต้องเข้าสู่ระบบผ่านเบราว์เซอร์เสมอ แม้แต่คีย์ที่รั่วไหลก็ไม่สามารถแตะต้องเงินหรือบัญชีของลูกค้าได้

กฎที่คุณวางใจได้

กฎ	Detail
Site-bound	คีย์จะใช้งานได้เฉพาะบนเว็บไซต์ (โดเมน) ที่ถูกสร้างขึ้นมาเท่านั้น
อัตราการจำกัดคำขอ	ต่อคีย์และต่อบัญชี: 120 และ 300 คำขอต่อนาทีตามค่าเริ่มต้น
Idempotency	การดำเนินการที่มีค่าใช้จ่ายหรือทำซ้ำไม่ได้จำเป็นต้องมีส่วนหัว Idempotency-Key
โควตา	คีย์จะต้องอยู่ภายใต้ quotas เดียวกันกับลูกค้า
Locked account	คีย์ของลูกค้าที่ถูกล็อกจะหยุดทำงาน (403 account_blocked).
Audit	การเพิกถอนโดยผู้ดูแลระบบจะถูกบันทึกไว้ในบันทึกการตรวจสอบของผู้ดูแลระบบ

มุมมองผู้ดูแลระบบ

1. เปิด Customers › API keys (/customers/apikeys). ตารางจะแสดงชื่อคีย์และอักขระตัวแรก, เจ้าของ, สโคป, สถานะ, การใช้งานล่าสุด (เวลา, จำนวนคำขอ, IP), และวันหมดอายุ.
2. กรองตามไซต์หากคุณมีรี셀러 ค้นหาตามชื่อ, ID หรือจุดเริ่มต้นของคีย์.
3. คลิก Revoke เพื่อหยุดคีย์ที่ใช้งานอยู่ หรือ Log เพื่อดูการใช้งาน.
4. ผู้ดูแลระบบสามารถดูและเพิกถอนคีย์ได้ แต่ไม่สามารถอ่านหรือสร้างคีย์ให้ลูกค้าได้.

ตรวจสอบ

1. สร้างคีย์ที่มีสโคป vm:read เท่านั้น.
2. curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" จะส่งคืนรายการ VM.
3. curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX" จะตอบกลับด้วย 403 scope_required.
4. เพิกถอนคีย์; การเรียกครั้งแรกจะตอบกลับด้วย 401 key_revoked.

ขีดจำกัดและหมายเหตุ

• คีย์จะไม่แสดงขึ้นมาอีก โปรดปฏิบัติต่อคีย์เสมือนรหัสผ่านและจัดเก็บไว้ในตัวจัดการความลับหรือ CI secret.
• แนะนำให้ใช้หนึ่งคีย์ต่อหนึ่งสคริปต์, สโคปที่น้อยที่สุด, วันหมดอายุที่สั้น และรายการ IP ที่อนุญาต; หมุนเวียนคีย์โดยการสร้างคีย์ใหม่และเพิกถอนคีย์เก่า.
• คีย์จากการเข้าสู่ระบบอุปกรณ์ (CLI, MCP) จะมีค่าเริ่มต้นเป็น 90 วัน.
• ทรัพยากรที่ถูกลบหรือโอนย้ายจะไม่ได้รับผลกระทบจากการเพิกถอนคีย์.

การแก้ Problme

อาการ	สาเหตุ	วิธีแก้ปัญหา
ข้อผิดพลาด too_many_keys (422)	ถึงขีดจำกัดของคีย์ที่ใช้งานอยู่ (ค่าเริ่มต้นคือ 10)	เพิกถอนคีย์เก่า.
ข้อผิดพลาด invalid_argument: ไม่ได้เลือกสโคป	ไม่ได้เลือกสโคปใดๆ	เลือกสโคปอย่างน้อยหนึ่งรายการ.
ข้อผิดพลาด invalid_argument บน IP ที่อนุญาต	รายการไม่ใช่ IP หรือช่วง, ความยาวคำนำหน้าผิด, หรือมีมากกว่า 20 รายการ	หนึ่ง IP หรือ CIDR ต่อบรรทัด เช่น 203.0.113.0/24.
การสร้างถูกปฏิเสธในระหว่างการสวมรอย	impersonate_forbidden	ขอให้ลูกค้าสร้างคีย์ดังกล่าว.
401 key_expired	พ้นกำหนดวันหมดอายุแล้ว	สร้างคีย์ใหม่.
401 key_ip_denied	IP ของผู้เรียกไม่อยู่ในรายการที่อนุญาต	เพิ่ม IP หรือล้างรายการ.
401 api_keys_disabled	ฟีเจอร์ถูกปิดใช้งาน	สอบถามผู้ดูแลระบบของคุณ (การตั้งค่า api_keys_enabled).