API 키 및 스코프
포털 위치: API keys (
/api-keys). 관리자 위치: Customers › Customers › API keys (/customers/apikeys).
작동 내용
API key를 사용하면 스크립트, CI 작업, cmp CLI 또는 AI 어시스턴트(MCP)가 부여된 권한(scopes) 범위 내에서 특정 고객을 대신하여 REST API를 호출할 수 있습니다. 고객 키는 vk_(으)로 시작합니다. 서비스 조회 및 관리는 가능하지만, 결제나 계정 자체는 절대 건드릴 수 없습니다.
요구 사항
| 항목 | 요구 사항 |
|---|---|
| Customer | 로그인된 포털 세션 (키는 다른 키를 생성 또는 편집할 수 없으며, 고객으로 가장한 관리자도 불가능합니다). |
| 스위치 | API 키는 기본적으로 켜져 있습니다. 꺼져 있는 경우 호출 시 401 api_keys_disabled을(를) 반환합니다. |
| 의존성 | 제품의 스코프는 해당 제품이 사이트에서 활성화된 경우에만 표시됩니다. |
키 생성 (고객)
포털에 로그인한 후 API keys를 엽니다.
Create key을(를) 클릭합니다.
양식을 작성합니다:
필드 규칙 Key name 필수 항목, 최대 60자 ("deploy server", "backup script"). 이 키로 수행할 수 있는 작업 필요한 스코프를 최소 하나 이상 선택하세요. 읽기 전용 키에는 쓰기 스코프를 부여하지 마세요. 과금이 발생하거나 데이터를 삭제하는 스코프는 주의해서 다루어야 합니다. Expiry 사용 안 함, 30일, 90일 또는 1년 (API는 1~3650일을 지원합니다). 지정된 IP에서만 호출 허용 줄당 하나의 IP 또는 CIDR 대역, 최대 20개 (IPv4 또는 IPv6). 비워두면 모든 IP를 허용합니다. 가능한 경우 서버의 IP를 고정하세요. 양식을 확인합니다. 키는 "Key created — shown ONCE" 창에 단 한 번 표시됩니다. 키를 복사한 후 I saved the key을(를) 클릭하세요. SHA-256 해시만 저장되므로 관리자조차 다시 확인할 수 없습니다. 분실한 경우 폐기하고 새로 생성해야 합니다.
포털에서는 키를 테스트할 수 있는 준비된
curl명령어 또한 제공합니다.
키는 vk_ 뒤에 긴 무작위 문자열이 붙는 형태입니다. 목록에는 처음 몇 자(예: vk_a1b2c3d4), 스코프, 만료일, 마지막 사용일, 요청 횟수 및 상태(Active, Expired, Revoked)만 표시됩니다.
편집, 폐기, 감사
- Edit는 이름, 스코프, 허용된 IP 및 만료일을 변경합니다. 대행 세션 중에는 허용되지 않습니다.
- Revoke는 키를 즉시 중지하며 취소할 수 없습니다. 사용 로그를 계속 확인할 수 있도록 행은 유지됩니다.
- Key usage log는 최근 60일 동안의 쓰기 명령어 및 모든 오류를 시간, 요청, 키, 결과, 소스 IP와 함께 표시합니다.
- 계정은 기본적으로 최대 10개의 활성 키를 보유할 수 있습니다.
- CLI 또는 MCP 로그인을 통해 생성된 키는 Connected apps & devices에 표시되며 해당 위치에서 취소할 수 있습니다.
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(으)로 응답합니다.
키가 절대 할 수 없는 일
금액 충전 또는 출금, 카드 또는 자동 충전 변경, 비밀번호·이메일·2FA 변경, 계정 삭제, 다른 키 생성·편집·취소는 어떠한 스코프로도 불가능합니다. 이 작업들은 항상 로그인된 브라우저가 필요합니다. 키가 유출되더라도 고객의 자금이나 계정에는 접근할 수 없습니다.
신뢰할 수 있는 규칙
| 규칙 | Detail |
|---|---|
| Site-bound | 키는 생성된 사이트(도메인)에서만 작동합니다. |
| 요청 제한 | 키별 및 계정별: 기본적으로 분당 120개 및 300개의 요청. |
| 멱등성 | 비용이 발생하거나 반복할 수 없는 작업에는 Idempotency-Key 헤더가 필요합니다. |
| 할당량 | 키는 고객과 동일한 quotas의 적용을 받습니다. |
| Locked account | 잠긴 고객의 키는 작동이 중지됩니다(403 account_blocked). |
| 감사 | 관리자에 의한 취소는 관리자 감사 로그에 기록됩니다. |
관리자 보기
- Customers › API keys(
/customers/apikeys)을 엽니다. 테이블에는 키 이름 및 첫 문자, 소유자, 범위, 상태, 최근 사용(시간, 요청 수, IP), 만료일이 표시됩니다. - 리셀러가 있는 경우 사이트별로 필터링합니다. 이름, ID 또는 키 시작 부분으로 검색합니다.
- 활성 키를 중지하려면 Revoke를 클릭하고, 사용 내역을 보려면 Log를 클릭합니다.
- 관리자는 키를 조회하고 취소할 수 있지만 고객을 위해 키를 읽거나 생성할 수는 없습니다.
확인
vm:read범위만 사용하여 키를 생성합니다.curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"은(는) VM 목록을 반환합니다.curl -s -X POST .../v1/vm/<id>/start -H "Authorization: Bearer vk_XXXX"은(는) 403scope_required(으)로 응답합니다.- 키를 취소합니다. 이제 첫 번째 호출은 401
key_revoked(으)로 응답합니다.
한도 및 참고 사항
- 키는 다시 표시되지 않습니다. 비밀번호처럼 취급하고 비밀 관리자나 CI 시크릿에 보관하세요.
- 스크립트당 하나의 키, 최소한의 범위, 짧은 만료 기간 및 IP 허용 목록을 사용하는 것이 좋습니다. 새 키를 생성하고 기존 키를 취소하여 교체하세요.
- 디바이스 로그인(CLI, MCP)의 키는 기본적으로 90일로 설정됩니다.
- 키를 취소해도 삭제되거나 이전된 리소스는 영향을 받지 않습니다.
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 설정). |