---
title: API keys และ scopes
description: วิธีที่ลูกค้าสร้าง API keys (คำนำหน้า vk_), เลือก scopes, จำกัดตาม IP และวันหมดอายุ รวมถึงวิธีที่ผู้ดูแลระบบตรวจสอบและเพิกถอน
url: https://nexcmp.com/th/docs/developers/api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# API keys และ scopes {#api-keys-and-scopes}

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

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

**API key** ช่วยให้สคริปต์, งาน CI, [`cmp` CLI](https://nexcmp.com/th/docs/developers/cmp-cli/) หรือผู้ช่วย AI ([MCP](https://nexcmp.com/th/docs/developers/mcp/)) สามารถเรียก [REST API](https://nexcmp.com/th/docs/developers/api/) ในนามของลูกค้าคนใดคนหนึ่งได้ โดยมีเฉพาะสิทธิ์ (**scopes**) ที่ได้รับอนุญาตเท่านั้น คีย์ของลูกค้าจะขึ้นต้นด้วย `vk_` สามารถอ่านและจัดการบริการได้แต่ **ไม่สามารถ** แตะต้องเรื่องเงินหรือตัวบัญชีได้

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

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

## สร้างคีย์ (สำหรับลูกค้า) {#create-a-key-customer}

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-revoke-audit}

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

## Scopes {#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`**

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

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

## กฎที่คุณวางใจได้ {#rules-you-can-rely-on}

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

## มุมมองผู้ดูแลระบบ {#administrator-view}

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

![รายการคีย์ API ของลูกค้าโดยผู้ดูแลระบบ พร้อมสโคป, สถานะ, การใช้งานล่าสุด และปุ่ม Revoke](https://nexcmp.com/th/docs/images/developers/api-keys-02-admin.webp)

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

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`.

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

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

## การแก้ Problme {#troubleshooting}

| อาการ | สาเหตุ | วิธีแก้ปัญหา |
|---|---|---|
| ข้อผิดพลาด `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`). |