---
title: Admin API keys
description: สร้างและเพิกถอน ak_ admin keys สำหรับ AI agents และสคริปต์ พร้อม 8 ขอบเขต, วันหมดอายุ, ช่วง IP, อัตราจำกัด, สิ่งที่คีย์ไม่มีวันทำได้ และรหัสข้อผิดพลาดทั้งหมด
url: https://nexcmp.com/th/docs/configure-with-ai/admin-api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# Admin API keys {#admin-api-keys}

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

## What it does {#what-it-does}

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

::: info ไม่เหมือนกับคีย์ของลูกค้า
ลูกค้าสร้างคีย์ที่ขึ้นต้นด้วย `vk_` ในพอร์ทัลลูกค้า ([API keys and scopes](https://nexcmp.com/th/docs/developers/api-keys/)) โดยคีย์เหล่านั้นจะเข้าถึงได้เฉพาะ customer API และ `/mcp` เท่านั้น คีย์ `ak_` จะถูกปฏิเสธบน customer API และคีย์ `vk_` จะถูกปฏิเสธบน admin API
:::

## ข้อกำหนด {#requirements}

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

## สร้างคีย์ {#create-a-key}

1. เปิด **System › Settings › API & AI agents** และอยู่บนแท็บ **API keys**
2. คลิก **Create new key**
3. กรอกข้อมูลในฟอร์ม:

   | ฟิลด์ | กฎ |
   |---|---|
   | Name | สูงสุด 60 ตัวอักษร เช่น "Claude Code on my laptop" |
   | Scopes | เลือกอย่างน้อยหนึ่งรายการ ดู [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** เพื่อรับคำสั่งที่พร้อมวางซึ่งมีคีย์ที่คุณเพิ่งสร้างเรียบร้อยแล้ว (เฉพาะในหน้านี้จนกว่าคุณจะรีโหลด)

![หน้าต่างสร้างคีย์ใหม่พร้อมชื่อ ช่องทำเครื่องหมายขอบเขต วันหมดอายุ และช่วง IP ที่กรอกแล้ว](https://nexcmp.com/th/docs/images/configure-with-ai/admin-api-keys-01-create.webp)

![หน้าต่างแสดงคีย์ใหม่ครั้งเดียวพร้อมปุ่มคัดลอกและคำเตือน](https://nexcmp.com/th/docs/images/configure-with-ai/admin-api-keys-02-shown-once.webp)

## Scopes {#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 โดยสามารถตั้งค่าได้แต่จะไม่สามารถอ่านค่ากลับมาได้ |

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

## การเพิกถอนคีย์ {#revoke-a-key}

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

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

## สิ่งที่คีย์ไม่สามารถทำได้เลย {#what-a-key-can-never-do}

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

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

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

### การดำเนินการที่ต้องได้รับการยืนยันจากคุณ {#actions-that-need-your-confirmation}

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

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

## การยืนยันแบบสองขั้นตอน {#two-step-confirmation}

เมื่อการเรียกใช้งานต้องการการยืนยัน จะยังไม่มีการเปลี่ยนแปลงใดๆ เกิดขึ้น ผลลัพธ์คือ 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-limit-and-ip-rules}

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

## บันทึกกิจกรรม {#activity-log}

แท็บ **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>` ด้วยเช่นกัน

![แท็บ Activity แสดงรายการการเรียกใช้งานพร้อมสถานะ ไคลเอนต์ เครื่องมือ และ IP](https://nexcmp.com/th/docs/images/configure-with-ai/admin-api-keys-03-activity.webp)

## ตรวจสอบ {#verify}

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

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

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

```bash
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](https://nexcmp.com/th/docs/configure-with-ai/mcp-admin/)

## ข้อผิดพลาด {#errors}

ข้อผิดพลาดจะอยู่ในรูปแบบ 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` | อาร์กิวเมนต์ของเครื่องมือขาดหายไป ไม่รู้จัก หรือมีประเภทที่ไม่ถูกต้อง ข้อความจะระบุชื่ออาร์กิวเมนต์ดังกล่าว | แก้ไขอาร์กิวเมนต์ |

## ขีดจำกัดและหมายเหตุ {#limits-notes}

- กำหนดให้คีย์มีอายุการใช้งานสั้นและมีสิทธิ์จำกัดแคบที่สุด ควรใช้หนึ่งคีย์ต่อหนึ่งไคลเอนต์เพื่อให้คุณสามารถเพิกถอนเฉพาะคีย์นั้นได้
- คีย์มีความสามารถตามสโคปของมัน `secrets:write` ร่วมกับ `billing:write` คือชุดค่าผสมที่มีความละเอียดอ่อนที่สุด การกระทำเกี่ยวกับเงินจะยังคงหยุดอยู่ที่ขั้นตอนตัวอย่าง
- คีย์ที่สร้างขึ้นโดยอัตโนมัติ (สำหรับ AI Chat และ CLI ของเซิร์ฟเวอร์) จะมีอายุใช้งานเพียงไม่กี่นาทีและทำงานจากเซิร์ฟเวอร์แผงควบคุมเท่านั้น
- หากต้องการตัดการเชื่อมต่อไคลเอนต์ AI ทันที ให้เพิกถอนคีย์ของไคลเอนต์นั้น การเชื่อมต่อ OAuth สามารถเพิกถอนได้ที่แท็บ **Connected apps** ([OAuth connectors](https://nexcmp.com/th/docs/configure-with-ai/oauth-connectors/))