Admin API keys

ตำแหน่งในหน้าผู้ดูแลระบบ: System › Settings › API & AI agents (/agent/keys), แท็บ API keys หน้าเดียวกันนี้ยังมีแท็บ Connect an AI, Connected apps และ Activity

What it does

Admin API key (มีคำนำหน้าว่า ak_) ช่วยให้ไคลเอนต์ AI หรือสคริปต์สามารถจัดการแผงควบคุมของคุณด้วยสิทธิ์ที่คุณกำหนดได้อย่างแม่นยำ โดยทำงานบน admin API ที่ /v1/admin/ และบน admin MCP endpoint /mcp/admin ซึ่งจะไม่ทำงานที่อื่น

ไม่เหมือนกับคีย์ของลูกค้า

ลูกค้าสร้างคีย์ที่ขึ้นต้นด้วย vk_ ในพอร์ทัลลูกค้า (API keys and scopes) โดยคีย์เหล่านั้นจะเข้าถึงได้เฉพาะ customer API และ /mcp เท่านั้น คีย์ ak_ จะถูกปฏิเสธบน customer API และคีย์ vk_ จะถูกปฏิเสธบน admin API

ข้อกำหนด

Item	Requirement
บทบาท	คุณต้องเข้าสู่ระบบในฐานะผู้ดูแลระบบ คีย์ไม่สามารถสร้างคีย์อื่นได้
เดโม	บนเดโมแผงควบคุม หน้าดังกล่าวจะเป็นแบบอ่านอย่างเดียว: ไม่สามารถสร้างหรือเพิกถอนคีย์ใดๆ ได้
การเข้าถึง	ไคลเอนต์ต้องสามารถเข้าถึง https://cloud.example.com/mcp/admin หรือ /v1/admin/... บนแผงควบคุมของคุณได้ (โปรดตรวจสอบไฟร์อลของคุณหากมีการใช้ข้อจำกัดด้าน IP)

สร้างคีย์

1. เปิด System › Settings › API & AI agents และอยู่บนแท็บ API keys

2. คลิก Create new key

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

   ฟิลด์	กฎ
   Name	สูงสุด 60 ตัวอักษร เช่น "Claude Code on my laptop"
   Scopes	เลือกอย่างน้อยหนึ่งรายการ ดู Scopes เริ่มต้นด้วย admin:read เท่านั้น
   วันหมดอายุ	1, 7, 30, 60 หรือ 90 วัน ค่าเริ่มต้นคือ 30 สูงสุด 90 ไม่สามารถสร้างคีย์ที่ไม่มีวันหมดอายุได้
   ช่วง IP (ไม่บังคับ)	ที่อยู่ IPv4 หรือ IPv6 หรือ CIDR หนึ่งรายการต่อบรรทัด เช่น 203.0.113.0/24 หรือ 2001:db8::/48 สูงสุด 32 รายการ เว้นว่างไว้เพื่ออนุญาตทุก IP
   จำนวนครั้งต่อนาที	1 ถึง 6000 ค่าเริ่มต้นคือ 120

4. คลิก Create key หน้าต่างจะแสดงคีย์เพียงครั้งเดียว เช่น ak_XXXX คัดลอกทันที: NexCMP จะจัดเก็บเฉพาะแฮชและจะไม่สามารถแสดงคีย์นี้ได้อีก

5. คลิก I have saved the key เปิดแท็บ Connect an AI เพื่อรับคำสั่งที่พร้อมวางซึ่งมีคีย์ที่คุณเพิ่งสร้างเรียบร้อยแล้ว (เฉพาะในหน้านี้จนกว่าคุณจะรีโหลด)

Scopes

คีย์สามารถใช้ได้เฉพาะเครื่องมือและเอนด์พอยต์ที่ขอบเขตของมันอนุญาตเท่านั้น ขอบเขตการเขียนจะไม่รวมสิทธิ์การอ่าน: คีย์ที่ต้องการอ่านและเขียนจึงต้องมี admin:read ด้วย

Scope	สิ่งที่อนุญาต
admin:read	อ่านการตั้งค่า แคตตาล็อก ลูกค้า การเรียกเก็บเงิน และบันทึกระบบ ข้อมูลลับจะไม่ถูกส่งคืน
catalog:write	แพ็กเกจ เทมเพลต OS โควตา รหัสส่วนลด
infra:write	แหล่งโครงสร้างพื้นฐาน (CloudStack, Proxmox), โซน, เซิร์ฟเวอร์
billing:write	เกตเวย์การชำระเงิน สกุลเงิน ใบแจ้งหนี้ ยอดคงเหลือ การทำธุรกรรมทางการเงินต้องมีการยืนยัน
customers:write	ลูกค้าและผู้แทนจำหน่าย
settings:write	การตั้งค่าทั่วไป, การสร้างแบรนด์, อีเมล, หน้ากฎหมาย, โมดูล และการแจ้งเตือน
ai:write	ผู้ให้บริการ AI และฟีเจอร์ AI
secrets:write	เขียนรหัสผ่านและ API keys โดยสามารถตั้งค่าได้แต่จะไม่สามารถอ่านค่ากลับมาได้

การตั้งค่าความลับต้องใช้ 2 สโคป

ทุกการเรียกใช้งานที่มีรหัสผ่าน, API key หรือค่าโทเค็น (เช่น รหัสผ่าน SMTP, คีย์การชำระเงิน, Telegram bot token, คีย์ผู้ให้บริการ AI, ข้อมูลรับรอง CloudStack หรือ Proxmox) จำเป็นต้องมี secrets:write และ สโคปของพื้นที่นั้น (ตัวอย่างเช่น settings:write สำหรับ SMTP) หากคุณต้องการพิมพ์ข้อมูลลับด้วยตัวเอง ให้เว้น secrets:write ไว้แล้วป้อนข้อมูลในหน้าผู้ดูแลระบบ

การเพิกถอนคีย์

1. ค้นหาคีย์ในตาราง (สถานะ Active, Expired หรือ Revoked; Last used จะแสดงเวลาและไคลเอนต์)
2. คลิก Revoke และยืนยัน

คีย์จะหยุดทำงานทันที การเพิกถอนเป็นการดำเนินการถาวร; ให้สร้างคีย์ใหม่หากต้องการใช้งานอีกครั้ง

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

คีย์จะไม่สามารถเข้าถึงพื้นที่เหล่านี้ได้ไม่ว่าจะมีสโคปใดก็ตาม ซึ่งต้องอาศัยการเข้าสู่ระบบในฐานะผู้ดูแลระบบ

• สร้างหรือเปลี่ยนแปลงผู้ใช้งานที่เป็นผู้ดูแลระบบ, 2FA และความปลอดภัยในการเข้าสู่ระบบ, เซสชันของผู้ดูแลระบบ และ admin API tokens
• สร้าง, แสดงรายการ หรือเพิกถอนคีย์ของผู้ดูแลระบบ, การเชื่อมต่อ OAuth และบัญชี AI หรือใช้งาน AI Console
• สำรองข้อมูลหรือกู้คืนพาเนล, อัปเดต หรือเปลี่ยนไลเซนส์
• เข้าสู่ระบบในฐานะลูกค้าหรือผู้แทนจำหน่าย, เปิดคอนโซลของลูกค้า, อ่านข้อมูลรับรอง VM หรือ kubeconfig, ตั้งค่า SSH keys, หรือส่งหรือรีเซ็ตรหัสผ่าน
• เปลี่ยนโมดูลเครือข่ายและการกำหนดเส้นทาง (BGP, FRR, RTBH, XDP, อินเทอร์เฟซ, เส้นทางแบบคงที่และนโยบาย, NAT) หรือเอเจนต์ภายนอกและการรวมพอร์ทัล ซึ่งเป็นแบบอ่านอย่างเดียว
• เปลี่ยนการตั้งค่าเช่น demo_*, admin_*, รายชื่อโฮสต์, passkey, การยืนยันตัวตนซ้ำ และความลับของ captcha

สิ่งใดก็ตามที่ไม่ได้ครอบคลุมโดยกฎจะถูกปิดกั้นสำหรับการเขียนโดยค่าเริ่มต้น และอ่านได้ด้วย admin:read สำหรับการอ่าน

การดำเนินการที่ต้องได้รับการยืนยันจากคุณ

การดำเนินการเหล่านี้จะสำเร็จก็ต่อเมื่อคุณอนุมัติการแสดงตัวอย่างแล้วเท่านั้น (ดู Two-step confirmation):

• การเปลี่ยนยอดเงินของลูกค้าหรือวอลเล็ตของผู้แทนจำหน่าย, การจ่ายเงิน, บันทึกการเรียกเก็บเงิน และอัตราแลกเปลี่ยน
• การเปลี่ยนราคา (ราคาแพลน, การสร้างแพลนจำนวนมาก, ราคาภาพและพื้นที่เก็บข้อมูล) และการสร้างส่วนลดหรือโค้ดเงิน
• การบันทึกข้อมูลรับรองเกตเวย์การชำระเงินหรือการเชื่อมต่อ CloudStack
• การลบสิ่งใดก็ตาม, ระงับหรือลบลูกค้า, เปลี่ยนขีดจำกัดของลูกค้า, ระงับหรือปิดผู้แทนจำหน่าย
• การดำเนินการบนเซิร์ฟเวอร์ของลูกค้า หรือการสร้างเซิร์ฟเวอร์แบบชำระเงินให้แก่ลูกค้า
• การเปลี่ยนแปลงสวิตช์ทั่วทั้งไซต์, การตั้งค่าความปลอดภัยในการเข้าสู่ระบบ หรือการตั้งค่าการชำระเงินผ่านการตั้งค่าทั่วไป

การยืนยันแบบสองขั้นตอน

เมื่อการเรียกใช้งานต้องการการยืนยัน จะยังไม่มีการเปลี่ยนแปลงใดๆ เกิดขึ้น ผลลัพธ์คือ HTTP 428 พร้อมด้วย confirm_required, confirm_token, preview (เมธอด, พาธ, เหตุผล, ค่าใหม่ และค่าปัจจุบันเมื่อมีข้อมูล) และ expires_in: 300

1. ไคลเอนต์จะแสดงตัวอย่างให้คุณเห็น
2. หลังจากที่คุณอนุมัติแล้ว ระบบจะทำคำขอ เดิม ซ้ำ (เมธอด, พาธ และเนื้อหาเดิม) พร้อมกับส่วนหัว X-Confirm-Token: <confirm_token> เครื่องมือ MCP จะใช้าร์กิวเมนต์ confirm_token แทน
3. โทเค็นนี้ใช้งานได้หนึ่งครั้งและจะหมดอายุหลังจาก 5 นาที

คีย์ที่สร้างขึ้นภายในผู้ดูแลระบบสำหรับ AI Chat สามารถยืนยันได้บนหน้าจอเท่านั้น: ผลลัพธ์จะระบุว่า confirm_in: "ui" และการ์ดยืนยันจะปรากฏขึ้นในหน้าผู้ดูแลระบบ AI ไม่สามารถอนุมัติได้

ขีดจำกัดอัตราและกฎ IP

• หากเกินขีดจำกัดต่อนาที การเรียกใช้งานจะส่งคืน rate_limited (HTTP 429) พร้อมกับ Retry-After: 60
• หากมีการตั้งค่าช่วง IP การเรียกใช้งานจากที่อยู่ IP อื่นจะส่งคืน ip_not_allowed (HTTP 403)

บันทึกกิจกรรม

แท็บ Activity จะแสดงรายการการเรียกใช้งานทั้งหมดที่ใช้คีย์ โดยเรียงจากล่าสุดไปเก่าสุด ได้แก่ เวลา คีย์ ไคลเอนต์ วิธีการส่งคำขอ (http, mcp, chat, cli, confirm, preview) เมธอดและพาธ เครื่องมือ สถานะ HTTP IP และรายละเอียด (แบบซ่อนข้อมูล) คุณสามารถค้นหาตามพาธ เครื่องมือ หรือชื่อคีย์ แสดงเฉพาะข้อผิดพลาด (HTTP 400 ขึ้นไป) หรือเฉพาะการเรียกใช้งานที่รอการยืนยัน (428 ขึ้นไป) และจำกัดช่วงเวลาเป็น 1 ชั่วโมงล่าสุด 24 ชั่วโมง หรือ 7 วันที่ผ่านมา NexCMP จะเก็บบันทึกลงรายการ 200,000 รายการล่าสุด การเปลี่ยนแปลงที่ทำผ่านคีย์จะปรากฏใน Logs › Admin actions ภายใต้ชื่อ ak:<admin>/<key name> ด้วยเช่นกัน

ตรวจสอบ

ทดสอบคีย์แบบอ่านอย่างเดียวจากเครื่องใดก็ได้ที่อยู่ในช่วง IP:

curl -s https://cloud.example.com/v1/admin/agent/tools \
  -H "Authorization: Bearer ak_XXXX"

คุณจะได้รับรายการ JSON ของเครื่องมือที่สโคปของคุณอนุญาต ลองรันดูสักหนึ่งรายการ:

curl -s -X POST https://cloud.example.com/v1/admin/agent/tools/system_health \
  -H "Authorization: Bearer ak_XXXX" \
  -H "Content-Type: application/json" -d '{}'

เวลา Last used ของคีย์จะถูกอัปเดต และการเรียกใช้งานจะปรากฏใน Activity รายการเครื่องมือทั้งหมดและคำอธิบาย OpenAPI (/v1/admin/openapi.json) อธิบายไว้ใน Connect an AI client

ข้อผิดพลาด

ข้อผิดพลาดจะอยู่ในรูปแบบ JSON: {"error": {"code": "...", "message": "..."}}

HTTP	code	ความหมาย	วิธีแก้ปัญหา
401	invalid_key	คีย์หายไป จัดรูปแบบไม่ถูกต้อง หรือไม่รู้จัก นอกจากนี้ยังแสดงผลเมื่อใช้คีย์ ak_ กับพาธที่ไม่ใช่ของผู้ดูแลระบบ	ตรวจสอบคีย์ และใช้งานบน /v1/admin/ และ /mcp/admin เท่านั้น
401	key_expired	คีย์หมดอายุแล้ว	สร้างคีย์ใหม่.
401	key_revoked	คีย์ถูกเพิกถอนแล้ว	สร้างคีย์ใหม่.
403	ip_not_allowed	IP ของผู้เรียกใช้งานอยู่นอกช่วง IP ของคีย์	โทรจาก IP ที่ได้รับอนุญาต หรือสร้างคีย์ด้วยช่วง IP ที่ถูกต้อง
403	local_only_key	คีย์ที่สร้างสำหรับ AI Chat หรือ CLI ของเซิร์ฟเวอร์ถูกใช้งานจากเครื่องอื่น	คีย์เหล่านี้ใช้งานได้บนเซิร์ฟเวอร์แผงควบคุมเท่านั้น
403	insufficient_scope	คีย์ไม่มีสโคป คำตอบประกอบด้วย required_scope	สร้างคีย์ที่มีสโคปดังกล่าว
403	forbidden_for_keys	ปลายทางหรือการตั้งค่าที่คุณพยายามเปลี่ยนแปลงถูกปิดกั้นไม่ให้ใช้คีย์	ดำเนินการดังกล่าวในหน้าผู้ดูแลระบบ
403	demo_read_only	แผงควบคุมอยู่ในโหมดทดลองใช้และมีการเรียกใช้งานที่เขียนข้อมูล	ใช้งานแผงควบคุมที่ไม่ได้อยู่ในโหมดทดลองใช้
403	confirm_in_ui	การกระทำนี้ต้องได้รับการยืนยันบนหน้าจอในระบบผู้ดูแลระบบ	อนุมัติการ์ดยืนยัน
428	confirm_required	ตัวอย่างพร้อมใช้งานแล้ว ไม่มีอะไรเปลี่ยนแปลง รวมอยู่ด้วย confirm_token	แสดงตัวอย่าง จากนั้นทำซ้ำด้วย X-Confirm-Token
409	confirm_expired	โทเค็นมีอายุมากกว่า 5 นาที	ส่งคำขออีกครั้งเพื่อรับตัวอย่างใหม่
409	confirm_mismatch	โทเค็นเป็นของคำขออื่น (เมธอด พาธ หรือเนื้อหาคำขอแตกต่างกัน)	ทำซ้ำคำขอเดิมอย่างแน่นอน
409	confirm_invalid	โทเค็นไม่รู้จักหรือถูกใช้งานไปแล้ว	ส่งคำขออีกครั้งเพื่อรับตัวอย่างใหม่
429	rate_limited	มีการเรียกใช้งานมากเกินไปในนาทีนี้	รอ Retry-After
400	invalid_path	พาธมีลำดับอักขระต้องห้าม	ใช้พาธแบบปกติ
413	too_large	เนื้อหาคำหมีขนาดใหญ่เกิน 10 MB	ส่งข้อมูลให้น้อยลง
400	invalid_argument	อาร์กิวเมนต์ของเครื่องมือขาดหายไป ไม่รู้จัก หรือมีประเภทที่ไม่ถูกต้อง ข้อความจะระบุชื่ออาร์กิวเมนต์ดังกล่าว	แก้ไขอาร์กิวเมนต์

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

• กำหนดให้คีย์มีอายุการใช้งานสั้นและมีสิทธิ์จำกัดแคบที่สุด ควรใช้หนึ่งคีย์ต่อหนึ่งไคลเอนต์เพื่อให้คุณสามารถเพิกถอนเฉพาะคีย์นั้นได้
• คีย์มีความสามารถตามสโคปของมัน secrets:write ร่วมกับ billing:write คือชุดค่าผสมที่มีความละเอียดอ่อนที่สุด การกระทำเกี่ยวกับเงินจะยังคงหยุดอยู่ที่ขั้นตอนตัวอย่าง
• คีย์ที่สร้างขึ้นโดยอัตโนมัติ (สำหรับ AI Chat และ CLI ของเซิร์ฟเวอร์) จะมีอายุใช้งานเพียงไม่กี่นาทีและทำงานจากเซิร์ฟเวอร์แผงควบคุมเท่านั้น
• หากต้องการตัดการเชื่อมต่อไคลเอนต์ AI ทันที ให้เพิกถอนคีย์ของไคลเอนต์นั้น การเชื่อมต่อ OAuth สามารถเพิกถอนได้ที่แท็บ Connected apps (OAuth connectors)