---
title: API 키 및 스코프
description: 고객이 API 키(vk_ 접두사)를 생성하고, 스코프를 선택하며, IP 및 만료일로 제한하는 방법과 관리자가 이를 검토하고 취소하는 방법을 설명합니다.
url: https://nexcmp.com/ko/docs/developers/api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# API 키 및 스코프 {#api-keys-and-scopes}

> **포털 위치:** API keys (`/api-keys`). **관리자 위치:** Customers › Customers › API keys (`/customers/apikeys`).

## 작동 내용 {#what-it-does}

**API key**를 사용하면 스크립트, CI 작업, [`cmp` CLI](https://nexcmp.com/ko/docs/developers/cmp-cli/) 또는 AI 어시스턴트([MCP](https://nexcmp.com/ko/docs/developers/mcp/))가 부여된 권한(**scopes**) 범위 내에서 특정 고객을 대신하여 [REST API](https://nexcmp.com/ko/docs/developers/api/)를 호출할 수 있습니다. 고객 키는 `vk_`(으)로 시작합니다. 서비스 조회 및 관리는 가능하지만, 결제나 계정 자체는 **절대** 건드릴 수 없습니다.

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| Customer | 로그인된 포털 세션 (키는 다른 키를 생성 또는 편집할 수 없으며, 고객으로 가장한 관리자도 불가능합니다). |
| 스위치 | API 키는 기본적으로 켜져 있습니다. 꺼져 있는 경우 호출 시 401 `api_keys_disabled`을(를) 반환합니다. |
| 의존성 | 제품의 스코프는 해당 제품이 사이트에서 활성화된 경우에만 표시됩니다. |

## 키 생성 (고객) {#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`), 스코프, 만료일, 마지막 사용일, 요청 횟수 및 상태(*Active*, *Expired*, *Revoked*)만 표시됩니다.

### 편집, 폐기, 감사 {#edit-revoke-audit}

- **Edit**는 이름, 스코프, 허용된 IP 및 만료일을 변경합니다. 대행 세션 중에는 허용되지 않습니다.
- **Revoke**는 키를 즉시 중지하며 취소할 수 없습니다. 사용 로그를 계속 확인할 수 있도록 행은 유지됩니다.
- **Key usage log**는 최근 60일 동안의 쓰기 명령어 및 모든 오류를 시간, 요청, 키, 결과, 소스 IP와 함께 표시합니다.
- 계정은 기본적으로 최대 **10개의 활성 키**를 보유할 수 있습니다.
- CLI 또는 MCP 로그인을 통해 생성된 키는 **Connected apps & devices**에 표시되며 해당 위치에서 취소할 수 있습니다.

## Scopes {#scopes}

스코프 이름은 `area:action` 형식입니다. 제공되는 스코프는 활성화한 제품에 따라 다릅니다.

| Scope | Allows |
|---|---|
| `catalog:read` | 플랜 및 카탈로그 읽기. |
| `vm:read` | VM, 메트릭 및 VM 인보이스 읽기. |
| `vm:write` | 전원 작업, 사소한 변경, 방화벽, 빠른 스냅샷. |
| `vm:create` | **VM 생성(요금 부과).** |
| `vm:plan` | **플랜 변경 또는 크기 조정(요금 부과).** |
| `vm:destroy` | **VM 삭제.** |
| `vm:restore` | **스냅샷에서 VM 복원(디스크 덮어쓰기).** |
| `vm:console` | VNC 콘솔 티켓 열기. |
| `sshkey:read`, `sshkey:write` | SSH 키 읽기, 추가 및 제거. |
| `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는 클러스터 관리자 권한). |
| `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` | Dedicated servers(지갑에서 주문 생성; 삭제 시 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-Key` 헤더가 필요합니다. |
| 할당량 | 키는 고객과 동일한 [quotas](https://nexcmp.com/ko/docs/billing/quotas/)의 적용을 받습니다. |
| Locked account | 잠긴 고객의 키는 작동이 중지됩니다(403 `account_blocked`). |
| 감사 | 관리자에 의한 취소는 관리자 감사 로그에 기록됩니다. |

## 관리자 보기 {#administrator-view}

1. **Customers › API keys**(`/customers/apikeys`)을 엽니다. 테이블에는 키 이름 및 첫 문자, 소유자, 범위, 상태, 최근 사용(시간, 요청 수, IP), 만료일이 표시됩니다.
2. 리셀러가 있는 경우 사이트별로 필터링합니다. 이름, ID 또는 키 시작 부분으로 검색합니다.
3. 활성 키를 중지하려면 **Revoke**를 클릭하고, 사용 내역을 보려면 **Log**를 클릭합니다.
4. 관리자는 키를 **조회하고 취소할 수 있지만** 고객을 위해 키를 읽거나 생성할 수는 없습니다.

![범위, 상태, 최근 사용 및 취소 버튼이 포함된 고객 API 키의 관리자 목록](https://nexcmp.com/ko/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 시크릿에 보관하세요.
- 스크립트당 하나의 키, 최소한의 범위, 짧은 만료 기간 및 IP 허용 목록을 사용하는 것이 좋습니다. 새 키를 생성하고 기존 키를 취소하여 교체하세요.
- 디바이스 로그인(CLI, MCP)의 키는 기본적으로 90일로 설정됩니다.
- 키를 취소해도 삭제되거나 이전된 리소스는 영향을 받지 않습니다.

## Troubleshooting {#troubleshooting}

| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 오류 `too_many_keys` (422) | 활성 키 제한(기본값 10개)에 도달함 | 오래된 키를 취소하세요. |
| 오류 `invalid_argument`: 선택된 범위 없음 | 선택된 범위가 없음 | 범위를 하나 이상 선택하세요. |
| 허용된 IP 관련 오류 `invalid_argument` | 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` 설정). |