KO
NexCMP 무료로 시작하기
NexCMP 1.6.1에 적용됩니다·업데이트됨 ·마크다운으로 보기

관리자 API 키 ​

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

작동 내용 ​

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

고객 키와 다름

고객은 vk_(으)로 시작하는 키를 고객 포털(API keys and scopes)에서 생성합니다. 해당 키는 고객 API 및 /mcp에만 접근할 수 있습니다. ak_ 키는 고객 API에서 거부되며, vk_ 키는 관리자 API에서 거부됩니다.

요구 사항 ​

항목요구 사항
역할관리자로 로그인해야 합니다. 키로는 다른 키를 생성할 수 없습니다.
데모데모 패널에서는 해당 페이지가 읽기 전용으로 설정되어 있어 키를 생성하거나 해지할 수 없습니다.
네트워크 접근성클라이언트가 패널의 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 탭을 열어 방금 만든 키가 이미 포함된 바로 붙여넣기 가능한 명령어를 확인하세요 (이 페이지에서만, 새로 고칠 때까지 유지됨).

이름, 권한 범위 체크박스, 만료일 및 IP 대역이 입력된 새 키 대화상자

복사 버튼과 경고와 함께 새 키를 한 번만 보여주는 대화상자

Scopes ​

키는 허용된 범위의 도구와 엔드포인트만 사용할 수 있습니다. 쓰기 권한 범위에는 읽기 권한이 포함되지 않으므로, 읽기와 쓰기가 모두 필요한 키는 admin:read도 함께 필요합니다.

Scope허용하는 작업
admin:read설정, 카탈로그, 고객, 빌링 및 로그 읽기. 보안 정보는 절대 반환되지 않습니다.
catalog:write플랜, OS 템플릿, 할당량, 할인 코드.
infra:write인프라 소스(CloudStack, Proxmox), 영역, 서버.
billing:write결제 게이트웨이, 통화, 인보이스, 잔액. 금액 관련 작업은 확인이 필요합니다.
customers:write고객 및 리셀러.
settings:write일반 설정, 브랜딩, 이메일, 법적 페이지, 모듈, 알림.
ai:writeAI 제공자 및 AI 기능.
secrets:write비밀번호 및 API 키를 작성합니다. 설정은 가능하지만 읽을 수는 없습니다.

비밀번호 설정에는 두 가지 범위가 필요합니다

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

키 취소 ​

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

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

키가 절대 할 수 없는 일 ​

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

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

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

확인이 필요한 작업 ​

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

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

2단계 확인 ​

호출에 확인이 필요한 경우 아직 변경되지 않습니다. 응답은 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_not_allowed (HTTP 403)을(를) 반환합니다.

활동 로그 ​

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 탭 목록

확인 ​

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에 설명되어 있습니다.

오류 ​

오류는 JSON 형식입니다: {"error": {"code": "...", "message": "..."}}.

HTTPcode의미해결 방법
401invalid_key키가 없거나 형식이 잘못되었거나 알 수 없습니다. 관리자가 아닌 경로에 ak_ 키가 사용된 경우에도 반환됩니다.키를 확인하세요. /v1/admin/ 및 /mcp/admin에서만 사용해야 합니다.
401key_expired키의 만료 기한이 지났습니다.새 키를 생성하세요.
401key_revoked키가 취소되었습니다.새 키를 생성하세요.
403ip_not_allowed호출자의 IP가 키의 IP 대역 외부입니다.허용된 IP에서 호출하거나 올바른 대역을 가진 키를 생성하세요.
403local_only_keyAI Chat 또는 서버 CLI용으로 생성된 키가 다른 머신에서 사용되었습니다.이 키들은 패널 서버 자체에서만 작동합니다.
403insufficient_scope키에 스코프가 없습니다. 응답에 required_scope이(가) 포함됩니다.해당 스코프를 가진 키를 생성하세요.
403forbidden_for_keys엔드포인트 또는 변경하려는 설정이 키에 닫혀 있습니다.관리자 페이지에서 수행하세요.
403demo_read_only패널이 데모 모드인 상태에서 쓰기 호출이 발생했습니다.데모가 아닌 패널을 사용하세요.
403confirm_in_ui이 작업은 관리자 화면에서 확인해야 합니다.확인 카드를 승인하세요.
428confirm_required미리보기가 준비되었으며 변경된 사항은 없습니다. confirm_token이(가) 포함됩니다.미리보기를 표시한 후 X-Confirm-Token을(를) 사용하여 다시 시도하세요.
409confirm_expired토큰이 5분을 초과했습니다.새 미리보기를 위해 요청을 다시 보내세요.
409confirm_mismatch토큰이 다른 요청에 속합니다(메서드, 경로 또는 본문이 다름).동일한 요청을 다시 수행하세요.
409confirm_invalid알 수 없거나 이미 사용된 토큰입니다.새 미리보기를 위해 요청을 다시 보내세요.
429rate_limited이번 분기에 너무 많은 호출이 발생했습니다.Retry-After을(를) 기다리세요.
400invalid_path경로에 금지된 시퀀스가 포함되어 있습니다.기본 경로를 사용하세요.
413too_large본문이 10 MB를 초과합니다.데이터를 줄여서 보내세요.
400invalid_argument도구 인수가 누락되었거나, 알 수 없거나, 잘못된 형식입니다. 메시지에 해당 이름이 표시됩니다.인수를 수정하세요.

한도 및 참고 사항 ​

  • 키의 유효 기간은 짧게 유지하고 권한은 최소화하세요. 단일 키를 쉽게 취소할 수 있도록 클라이언트당 하나의 키를 사용하는 것이 좋습니다.
  • 키의 성능은 권한 범위에 비례합니다. secrets:write 및 billing:write의 조합이 가장 민감하며, 금전적 작업은 여전히 미리보기에서 중지됩니다.
  • 자동으로 생성된 키(AI Chat, 서버 CLI용)는 몇 분 동안만 유지되며 패널 서버에서만 작동합니다.
  • AI 클라이언트를 즉시 차단하려면 키를 취소하세요. OAuth 연결은 Connected apps 탭(OAuth connectors)에서 취소할 수 있습니다.