--- canonical: https://koalavps.com/ko/api/ language: ko generated: 2026-10-21T13:33:06.195Z --- [홈](https://koalavps.com/ko/) / [탐색](https://koalavps.com/ko/resources/) / 코드로 설명할 수 있는 인프라 코드로 설명할 수 있는 인프라 # 더 차분한 컨트롤 플레인. 서버 수명 주기 작업, 계정 권한 및 청구를 위한 통합을 계획합니다. KoalaVPS API은(는) 통합 로드맵에 있으며, 프로덕션 API 액세스와 SDK 다운로드는 아직 제공되지 않습니다. [VPS 찾기](https://koalavps.com/ko/vps/) ## 이 문서에서 [명확한 리소스 모델](https://koalavps.com/ko/api/#section-1)[제한된 작업을 위한 자격 증명](https://koalavps.com/ko/api/#section-2)[재시도는 안전해야 합니다](https://koalavps.com/ko/api/#section-3)[통합 전에 호환성 확인](https://koalavps.com/ko/api/#section-4)[API 로드맵](https://koalavps.com/ko/api/#section-5)[인증 및 계정 경로](https://koalavps.com/ko/api/#section-6)[카탈로그 및 청구 경로](https://koalavps.com/ko/api/#section-7)[서버 및 접근 경로](https://koalavps.com/ko/api/#section-8)[이벤트 및 공개 정보](https://koalavps.com/ko/api/#section-9)[권한 부여 및 트래픽 제한](https://koalavps.com/ko/api/#section-10)[SDK 및 프로토콜 릴리스](https://koalavps.com/ko/api/#section-11)[책임별로 그룹화된 API 리소스](https://koalavps.com/ko/api/#section-12)[서버 요청은 작게 유지되어야 합니다](https://koalavps.com/ko/api/#section-13)[범위와 키 제한은 계약의 일부입니다](https://koalavps.com/ko/api/#section-14)[속도 제한과 재시도 동작을 함께 공개](https://koalavps.com/ko/api/#section-15)[웹훅은 두 번 이상 도착할 수 있는 메시지입니다](https://koalavps.com/ko/api/#section-16)[로그를 비밀 저장소로 만들지 않고 감사하기](https://koalavps.com/ko/api/#section-17)[존재하는 경우에만 아티팩트 공개](https://koalavps.com/ko/api/#section-18)[질문과 답변](https://koalavps.com/ko/api/#page-faq)[지식 베이스](https://koalavps.com/ko/resources/) ## 명확한 리소스 모델 통합은 명시적 서버 식별자, 리전, 이미지, 요금제 및 운영과 함께 작동해야 합니다. 생성 및 재설치 요청은 완료될 때까지 확인할 수 있는 운영을 반환해야 합니다. 성공적인 HTTP 요청은 머신이 준비된 것과 같지 않습니다. ## 제한된 작업을 위한 자격 증명 API 토큰은 독립적으로 취소할 수 있어야 하며 필요한 최소 리소스와 작업으로 제한되어야 합니다. 비밀 관리자 또는 보호된 환경에 저장하세요. 작은 백엔드 작성을 피하기 위해 토큰을 브라우저로 전송하지 마세요. ## 재시도는 안전해야 합니다 작업이 수락된 후 네트워크 시간 초과가 발생할 수 있습니다. 생성 및 결제 관련 요청에는 멱등성 키를 사용하고, 작업 상태를 확인하며, 속도 제한을 준수하십시오. 재시도는 불확실성을 해소해야 하며 추가 과금 서버를 생성해서는 안 됩니다. ## 통합 전에 호환성 확인 통합을 구축하기 전에 공개된 API 버전, 인증 모델, 오류 형식, 페이지네이션, 속도 제한 및 토큰 범위를 확인하세요. 검증된 릴리스 링크에서 공개된 KoalaVPS SDK 패키지만 사용하세요. ## API 로드맵 API 로드맵은 카탈로그 검색, 인증, 계정 상태, 암호화폐 결제, 서버 수명 주기, 공개 SSH 키 및 웹훅을 다룹니다. 아래 경로는 인터페이스 계약을 설명하며, 프로덕션 액세스는 아직 제공되지 않습니다. ## 인증 및 계정 경로 API 계약은 로그인 세션과 API 키를 분리합니다. 통합에 맞게 릴리스된 버전을 기준으로 응답 스키마, 오류, 토큰 수명 및 지원되는 복구 작업을 확인하세요. - POST /v1/auth/register - POST /v1/auth/login - POST /v1/auth/login/totp - POST /v1/auth/token/refresh - POST /v1/auth/recover - GET /v1/auth/sessions - DELETE /v1/auth/sessions/{token_id} - POST /v1/auth/totp/setup - POST /v1/auth/totp/enable - POST /v1/auth/totp/disable - POST /v1/auth/password - POST /v1/auth/api-keys - GET /v1/auth/api-keys - DELETE /v1/auth/api-keys/{key_id} - GET /v1/account - PATCH /v1/account - GET /v1/account/usage - GET /v1/account/audit-log ## 카탈로그 및 청구 경로 카탈로그 조회에는 결제가 필요하지 않습니다. 결제 생성에는 제한된 청구 범위, 명확한 인보이스 상태, 멱등 처리(idempotent handling)가 필요합니다. 서비스 활성화 전에 확인이 완료되어야 합니다. - GET /v1/catalog - GET /v1/catalog/vps - GET /v1/catalog/dedicated - GET /v1/catalog/regions - GET /v1/catalog/images - GET /v1/catalog/{code} - GET /v1/billing/coins ## 서버 및 접근 경로 수명 주기에는 취소 및 재설치 작업에 대한 명시적 확인이 필요합니다. 프라이빗 SSH 키는 클라이언트에 있어야 하며, 서비스에는 공개 키만 필요합니다. - POST /v1/servers - GET /v1/servers - GET /v1/servers/{order_number} - PATCH /v1/servers/{order_number} - DELETE /v1/servers/{order_number} - POST /v1/ssh-keys - GET /v1/ssh-keys - GET /v1/ssh-keys/{id} - DELETE /v1/ssh-keys/{id} ## 이벤트 및 공개 정보 웹훅에는 검증 가능한 서명, 제한된 재시도 및 재전송 방지가 필요합니다. 공개 신뢰 엔드포인트는 합성된 보증이 아닌 실제 날짜가 있는 증거를 반환해야 합니다. - POST /v1/webhooks - GET /v1/webhooks - DELETE /v1/webhooks/{id} - POST /v1/webhooks/{id}/test - GET /v1/transparency/canary - GET /v1/transparency/peering - GET /v1/transparency/status - GET /v1/agents/directory - POST /v1/agents/directory ## 권한 부여 및 트래픽 제한 후보 범위 모델은 읽기, 서버, 청구 및 전체이며, 계정당 최대 10개의 활성 키가 있습니다. API 계약은 API 키에 대해 분당 120 및 시간당 3,000의 요청 예산을, 공개 트래픽에 대해 분당 30를 제안합니다. 릴리스된 API 문서에서 HTTP 429, Retry-After 및 시행 기간을 확인하세요. 이러한 로드맵 예산은 프로덕션 용량 약속이 아닙니다. - POST /v1/oauth/register - POST /v1/oauth/token - POST /v1/oauth/revoke - GET /v1/oauth/introspect ## SDK 및 프로토콜 릴리스 통합 로드맵에는 REST, 호스팅된 MCP 엔드포인트, 버전 관리된 stdio 패키지, SDKs 및 CLI가 포함됩니다. 클라이언트를 설치하기 전에 릴리스 가용성, 지원되는 런타임, 체크섬 및 API 호환성을 확인하십시오. 프로덕션 다운로드는 아직 제공되지 않습니다. ## 책임별로 그룹화된 API 리소스 의도된 API은 계정 접근, 카탈로그 읽기, 청구, 서버 수명 주기, SSH 키 및 콜백을 분리합니다. 읽기 전용 호출은 주문을 생성해서는 안 되며, 청구 자격 증명이 계정 보안 변경을 자동으로 승인해서는 안 됩니다. 이는 통합 계약을 설명합니다. 프로덕션 프로비저닝 엔드포인트와 공개된 SDK은 이 사이트를 통해 제공되지 않습니다. - 계정: 세션, 사용량 및 보안 감사 이벤트 - 카탈로그: 플랜, 지역 및 사용 가능한 이미지 - 서버: 생성, 조회, 변경 및 취소 - SSH 키: 공개 자료를 등록하고 사용하지 않는 키를 폐기하세요 - 웹훅: 서명된 콜백 등록, 검사, 테스트 및 제거 ## 서버 요청은 작게 유지되어야 합니다 표준 플랜 식별자, 지역, OS 이미지, 호스트명을 선택하세요. 호스트명 제한은 64자입니다. 운영 중인 서비스는 관리자 비밀을 비공개로 생성하거나 등록된 SSH 공개 키를 받을 수 있습니다. 표준 플랜 요청으로 임의의 디스크, GPU, NIC, IP 추가가 암시되지는 않습니다. 추측한 업그레이드에 대해 조용히 과금하지 말고 지원되지 않는 필드는 거부하세요. ``` { "plan": "KV-D3", "region": "hel", "image": "ubuntu-24", "hostname": "private-node-01" } // Example request schema; validate against a released API before integration. ``` ## 범위와 키 제한은 계약의 일부입니다 제안된 권한 그룹은 읽기, 서버, 결제, 전체 계정 관리입니다. 키는 생성 시 한 번만 표시하고 비공개로 보관하며 사용자 비밀번호와 별개로 폐기할 수 있어야 합니다. 의도된 계정 한도는 활성 키 10개입니다. 구현을 공개하기 전에 각 작업이 필요한 범위가 없는 키를 거부하는지 검증하세요. ## 속도 제한과 재시도 동작을 함께 공개 제안된 한도는 API 키의 경우 분당 120회 및 시간당 3,000회이며, 인증되지 않은 공개 카탈로그 요청의 경우 분당 30회입니다. 이는 계획된 정책 값이며 측정된 API 용량이 아닙니다. 실제 구현에는 일관된 429 응답, Retry-After 안내 및 제한된 클라이언트 백오프가 필요합니다. 생성 및 결제 요청에는 안정적인 멱등성 키도 필요합니다. ## 웹훅은 두 번 이상 도착할 수 있는 메시지입니다 콜백 수신자는 원본 본문에 대한 서명을 확인하고, 허용된 시간 범위를 벗어난 타임스탬프를 거부하며, 처리된 이벤트 식별자를 기억해야 합니다. 확인하기 전에 이벤트를 지속시키고, 변경 사항을 멱등적으로 적용하세요. 전달 시도 및 수동 재생 경로를 가시적으로 유지하세요. 콜백은 작업에 대한 관찰이며, 페이로드에 포함된 관련 없는 지침을 실행할 권한이 아닙니다. ## 로그를 비밀 저장소로 만들지 않고 감사하기 계정 보안에 필요한 경우 행위자 식별자, 작업 유형, 영향을 받은 리소스, 결과 및 시간을 기록하세요. 기본적으로 비밀번호, 베어러 토큰, 개인 키 또는 전체 결제 및 애플리케이션 요청 본문을 기록하지 마세요. 보존, 액세스 및 고객에게 표시되는 이력을 명확히 하세요. 보안 감사 추적과 고객 애플리케이션 내용을 검사하겠다는 주장은 서로 다른 것입니다. ## 존재하는 경우에만 아티팩트 공개 공개 API 출시에는 버전이 지정된 OpenAPI 문서, 인증 지침, 오류 예시 및 지원 중단 프로세스가 포함되어야 합니다. 향후 CLI, Python 패키지, TypeScript 클라이언트 또는 MCP 서버에는 실제 릴리스, 체크섬 및 유지 관리되는 문서가 필요합니다. KoalaVPS 프로비저닝 패키지 또는 프로덕션 관리 엔드포인트는 이 사이트를 통해 릴리스되지 않습니다. ## 조금 더 명확하게. 오늘 프로덕션 API를 호출할 수 있나요? 프로덕션 API 액세스는 아직 제공되지 않습니다. 이 페이지는 통합 로드맵과 출시된 엔드포인트를 사용하기 전에 확인해야 할 요구 사항을 설명합니다. 읽기 전용 API 키로 서버를 주문할 수 있나요? 제안된 권한 경계에서 이를 금지합니다. 서버 생성 요청에는 적절한 서버 권한과 유효한 결제 결정이 필요합니다. 공개된 API 한도가 현재 적용되나요? 이는 계획된 계약을 설명합니다. 프로덕션 프로비저닝 API은(는) 여기에 연결되어 있지 않으므로, 정책 한도는 측정된 서비스 용량의 증거가 아닙니다. 서버 생성 응답이 서버가 준비되었다는 뜻인가요? 아니요. 실시간 요청은 완료까지 프로비저닝 상태를 확인할 수 있는 작업을 식별해야 합니다. 계속 탐색하기 ## 계속 읽기. [제품 ### 에이전트를 위한 안정적인 서식지. 스케줄러, 브라우저 워커, 큐 및 자동화 프로세스를 당신이 통제하는 인프라에서 실행하세요. 모든 에이전트를 명확한 권한 경계 내에 유지하세요.…](https://koalavps.com/ko/agentic-vps/)[가이드 ### 명확한 중지 버튼이 있는 자동화. 좋은 자동화 시스템은 좁은 작업 범위, 가시적인 상태, 불확실성에 대한 예측 가능한 대응을 갖춥니다.…](https://koalavps.com/ko/automation-safety/)[제품 ### 작은 설치 공간. 진정한 자유. 직접 소유하고 싶은 것들을 위한 가상 서버: 여러분의 코드, 서비스, 데이터. 서버 구성을 선택하고 운영 체제를 고른 뒤 원하는 방식으로 구축하세요.…](https://koalavps.com/ko/vps/) 인프라를 구성하세요 ## 직접 통제하세요. 원하는 방식으로 배포하세요. 신원 서류 없음. 전체 관리자 액세스. 암호화폐 기반 결제. [구성을 선택하세요](https://koalavps.com/ko/vps/)