---
title: 관리자 API 키
description: AI Agent 및 스크립트용 ak_ 관리자 키 생성과 해지: 8가지 scope, 만료 기간, IP 대역, rate limit, 키로 불가능한 작업 및 모든 오류 코드.
url: https://nexcmp.com/ko/docs/configure-with-ai/admin-api-keys/
applies_to: NexCMP 1.6.1
updated: 2026-11-02
---

# 관리자 API 키 {#admin-api-keys}

> **관리자 위치:** System › Settings › API & AI agents (`/agent/keys`), **API keys** 탭. 동일한 페이지에 **Connect an AI**, **Connected apps**, **Activity** 탭도 있습니다.

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

관리자 API 키(접두사 `ak_`)를 사용하면 AI 클라이언트 또는 스크립트가 부여된 권한에 한해 패널을 관리할 수 있습니다. `/v1/admin/` 경로의 관리자 API 및 관리자 MCP 엔드포인트 `/mcp/admin`에서 작동하며, 그 외 다른 곳에서는 작동하지 않습니다.

::: info 고객 키와 다름
고객은 `vk_`(으)로 시작하는 키를 고객 포털([API keys and scopes](https://nexcmp.com/ko/docs/developers/api-keys/))에서 생성합니다. 해당 키는 고객 API 및 `/mcp`에만 접근할 수 있습니다. `ak_` 키는 고객 API에서 거부되며, `vk_` 키는 관리자 API에서 거부됩니다.
:::

## 요구 사항 {#requirements}

| 항목 | 요구 사항 |
|---|---|
| 역할 | 관리자로 로그인해야 합니다. 키로는 다른 키를 생성할 수 없습니다. |
| 데모 | 데모 패널에서는 해당 페이지가 읽기 전용으로 설정되어 있어 키를 생성하거나 해지할 수 없습니다. |
| 네트워크 접근성 | 클라이언트가 패널의 `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/ko/docs/images/configure-with-ai/admin-api-keys-01-create.webp)

![복사 버튼과 경고와 함께 새 키를 한 번만 보여주는 대화상자](https://nexcmp.com/ko/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 키를 작성합니다. 설정은 가능하지만 읽을 수는 없습니다. |

::: tip 비밀번호 설정에는 두 가지 범위가 필요합니다
비밀번호, API 키 또는 토큰 값을 전송하는 모든 호출(SMTP 비밀번호, 결제 키, 텔레그램 봇 토큰, AI 제공자 키, CloudStack 또는 Proxmox 자격 증명)에는 `secrets:write` **및** 해당 영역의 범위(예: SMTP의 경우 `settings:write`)가 필요합니다. 비밀번호를 직접 입력하려면 `secrets:write`를 비워두고 관리자 페이지에서 입력하세요.
:::

## 키 취소 {#revoke-a-key}

1. 테이블에서 키를 찾습니다(상태는 **Active**, **Expired** 또는 **Revoked**이며, **Last used**는 시간과 클라이언트를 표시합니다).
2. **Revoke**를 클릭하고 확인합니다.

키가 즉시 작동을 멈춥니다. 취소는 영구적이므로 다시 필요한 경우 새 키를 만드세요.

## 키가 절대 할 수 없는 일 {#what-a-key-can-never-do}

어떤 범위를 가지든 키는 이러한 영역에 절대 접근할 수 없습니다. 관리자 로그인이 필요합니다.

- 관리자 사용자 생성 또는 변경, 2FA 및 로그인 보안, 관리자 세션, 관리자 API 토큰.
- 관리자 키, OAuth 연결, AI 계정 생성·목록 조회·취소 또는 AI 콘솔 사용.
- 패널 백업 또는 복원, 업데이트, 라이선스 변경.
- 고객 또는 리셀러로 로그인, 고객 콘솔 열기, VM 자격 증명 또는 kubeconfig 읽기, SSH 키 설정, 비밀번호 전송 또는 재설정.
- 네트워크 및 라우팅 모듈(BGP, FRR, RTBH, XDP, 인터페이스, 정적 및 정책 라우트, NAT) 또는 외부 에이전트 및 포털 통합 변경. 이는 읽기 전용입니다.
- `demo_*`, `admin_*`, 호스트 목록, 패스키, 재인증 및 캡차 비밀번호 등의 설정 변경.

규칙에 포함되지 않은 모든 항목은 쓰기의 경우 기본적으로 차단되며, 읽기의 경우 `admin:read`을 통해 읽을 수 있습니다.

### 확인이 필요한 작업 {#actions-that-need-your-confirmation}

다음 작업은 미리보기를 승인한 후에만 성공합니다([Two-step confirmation](#two-step-confirmation) 참조):

- 고객 잔액 또는 리셀러 월렛 변경, 자금 지금, 결제 기록, 환율.
- 가격 변경(플랜 가격, 대량 플랜 생성, 이미지 및 스토리지 가격 책정) 및 할인 또는 금액 코드 생성.
- 결제 게이트웨이 자격 증명 또는 CloudStack 연결 저장.
- 모든 항목 삭제, 고객 차단 또는 삭제, 고객 한도 변경, 리셀러 일시 정지 또는 종료.
- 고객 서버 제어 또는 고객을 위한 유료 서버 생성.
- 일반 설정을 통한 사이트 전체 스위치, 로그인 보안 설정 또는 결제 설정 변경.

## 2단계 확인 {#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_not_allowed` (HTTP 403)을(를) 반환합니다.

## 활동 로그 {#activity-log}

**Activity** 탭에는 키로 수행된 모든 호출이 최신순으로 나열됩니다. 시간, 키, 클라이언트, 유입 경로(`http`, `mcp`, `chat`, `cli`, `confirm`, `preview`), 메서드 및 경로, 도구, HTTP 상태, IP 및 (마스킹된) 상세 정보가 표시됩니다. 경로, 도구 또는 키 이름으로 검색하고, 오류(HTTP 400 이상)나 확인 대기 중인 호출(428 이상)만 필터링하며, 기간을 최근 1시간, 24시간 또는 7일로 제한할 수 있습니다. NexCMP는 최신 200,000개의 항목을 보관합니다. 키를 통해 수행된 변경 사항은 `ak:<admin>/<key name>` 이름으로 Logs › Admin actions에도 표시됩니다.

![상태, 클라이언트, 도구 및 IP가 표시된 Activity 탭 목록](https://nexcmp.com/ko/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/ko/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에서 호출하거나 올바른 대역을 가진 키를 생성하세요. |
| 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/ko/docs/configure-with-ai/oauth-connectors/))에서 취소할 수 있습니다.