API 사용 가이드

카카오클라우드 API를 사용하면 BCS, Networking 등 카카오클라우드 서비스를 코드로 호출하고 관리할 수 있습니다. API를 호출하려면 먼저 사용할 API와 엔드포인트를 확인한 후, IAM 액세스 키로 API 인증 토큰을 발급해야 합니다.

필요한 API는 API 인덱스에서 찾을 수 있습니다. 엔드포인트를 선택하면 호출 호스트와 주요 작업, 관련 API를 확인할 수 있습니다. 퍼블릭 IP나 볼륨처럼 하나의 리소스가 여러 엔드포인트에 걸쳐 제공되는 경우에는 작업에 맞는 API 찾기에서 적합한 API를 확인할 수 있습니다.

사이드바의 API 검색 창에서 서비스명이나 API 이름을 검색하면 원하는 API 문서를 빠르게 찾을 수 있습니다.

API 사용 준비

카카오클라우드에서 제공하는 API를 사용하기 위해 수행해야 하는 사전 작업은 다음과 같습니다.

액세스 키 발급

IAM 사용자 자격 증명인 IAM 액세스 키(Access key)는 IAM 액세스 키 ID와 보안 액세스 키를 의미하며, API 인증 토큰 발급을 위해 필요한 정보입니다. 발급 시 선택한 프로젝트에서 부여받은 IAM 역할에 따라 액세스 키의 권한이 주어집니다.

IAM 액세스 키는 카카오클라우드 콘솔 > 우측 상단 프로필 > 자격 증명 > IAM 액세스 키에서 발급/조회할 수 있습니다.

보안 액세스 키 보호

보안 액세스 키는 액세스 키 생성 시점에만 확인할 수 있습니다. 안전한 위치에 보관하고 문서, 코드, 로그 또는 Git 저장소에 포함하지 마세요.

API 인증 토큰 발급

API를 사용하려면 'API 인증 토큰'을 발급받아야 합니다. API 인증 토큰은 사용자 ID와 비밀번호를 대신하여 사용자를 인증하고 API에 접근할 수 있는 권한을 부여합니다. CLI나 API에서 API 인증 토큰을 사용하여 인증하고, 카카오클라우드 서비스를 이용할 수 있습니다.

API 인증 토큰을 발급받는 방법은 파라미터 구성에 따라 두 가지 방식으로 구분됩니다.

구분	필요한 파라미터
방법 1: 액세스 키 ID로 발급	IAM 액세스 키 ID, 보안 액세스 키
방법 2: 액세스 키 이름으로 발급	IAM 액세스 키의 이름, 보안 액세스 키, 사용자 고유 ID

토큰 발급 요청의 공통 URL과 헤더는 다음과 같습니다. 두 방식은 요청 본문에 지정하는 자격 증명 정보가 다릅니다.

POST https://iam.kakaocloud.com/identity/v3/auth/tokens
Content-Type: application/json

발급된 토큰은 응답 헤더의 X-Subject-Token에서 확인합니다.

방법 1: 액세스 키 ID로 발급

API 인증 토큰을 발급받는 첫 번째 방법에서는 IAM 액세스 키 ID와 보안 액세스 키를 사용합니다. 자세한 발급 방법은 다음과 같습니다.

요청 본문에 다음 자격 증명 정보를 지정합니다.

API 인증 토큰 발급 방법 1
{
    "auth": {
        "identity": {
            "methods": [
                "application_credential"
            ],
            "application_credential": {
                "id": "${IAM 액세스 키 ID}",
                "secret": "${보안 액세스 키}"
            }
        }
    }
}

환경변수	설명
IAM 액세스 키 ID🖌︎	액세스 키 생성 시점 또는 액세스 키 목록에서 해당 액세스 키 항목을 클릭하여 조회 가능
보안 액세스 키🖌︎	액세스 키 생성 시점에만 조회 가능

파라미터	필수 여부	설명
id	필수	IAM 액세스 키 ID - 액세스 키 생성 시점 또는 액세스 키 목록에서 해당 액세스 키를 클릭하여 조회 가능
secret	필수	보안 액세스 키 - 액세스 키 생성 시점에만 조회 가능

다음 curl 예제로 토큰을 발급받을 수 있습니다.

API 인증 토큰 발급 방법 1 curl 예시
curl -i -X POST "https://iam.kakaocloud.com/identity/v3/auth/tokens" \
-H "Content-Type: application/json" \
-d '{
    "auth": {
        "identity": {
            "methods": [
                "application_credential"
            ],
            "application_credential": {
                "id": "{IAM_ACCESS_KEY_ID}",
                "secret": "{SECRET_ACCESS_KEY}"
            }
        }
    }
}'

방법 2: 액세스 키 이름으로 발급

API 인증 토큰을 발급받는 두 번째 방법에서는 IAM 액세스 키의 이름, 보안 액세스 키, 사용자 고유 ID를 사용합니다. 자세한 발급 방법은 다음과 같습니다.

요청 본문에 다음 자격 증명 정보를 지정합니다.

API 인증 토큰 발급 방법 2
{
    "auth": {
        "identity": {
            "methods": [
                "application_credential"
            ],
            "application_credential": {
                "name": "${IAM 액세스 키 이름}",
                "secret": "${보안 액세스 키}",
                "user": {
                    "id": "${사용자 고유 ID}"
                }
            }
        }
    }
}

환경변수	설명
IAM 액세스 키 이름🖌︎	카카오클라우드 콘솔 > 우측 상단 프로필 > 자격 증명 > IAM 액세스 키에서 조회 가능
보안 액세스 키🖌︎	액세스 키 생성 시점에만 조회 가능
사용자 고유 ID🖌︎	카카오클라우드 콘솔 > 사용자 프로필 > 계정 정보에서 조회 가능

항목	필수 여부	설명
name	필수	IAM 액세스 키의 이름(직접 입력한 값) - 카카오클라우드 콘솔 > 우측 상단 프로필 > 자격 증명 > IAM 액세스 키에서 조회 가능
secret	필수	보안 액세스 키 - 액세스 키 생성 시점에만 조회 가능
user.id	필수	사용자 고유 ID - 카카오클라우드 콘솔 > 사용자 프로필 > 계정 정보에서 조회 가능

다음 curl 예제로 토큰을 발급받을 수 있습니다.

API 인증 토큰 발급 방법 2 curl 예시
curl -i -X POST "https://iam.kakaocloud.com/identity/v3/auth/tokens" \
-H "Content-Type: application/json" \
-d '{
    "auth": {
        "identity": {
            "methods": [
                "application_credential"
            ],
            "application_credential": {
                "name": "{IAM_ACCESS_KEY_NAME}",
                "secret": "{SECRET_ACCESS_KEY}",
                "user": {
                    "id": "{USER_ID}"
                }
            }
        }
    }
}'

API 요청 구성

요청 URL은 엔드포인트의 기본 URL과 API 경로로 구성됩니다. 예를 들어 Get instance type의 요청은 다음과 같습니다.

GET https://bcs.kr-central-2.kakaocloud.com/api/v1/flavors/{flavor_id}

위 요청에서 bcs는 엔드포인트 이름, kr-central-2는 리전이며, /api/v1/flavors/{flavor_id}는 API 경로입니다. {flavor_id}에는 조회할 인스턴스 유형의 ID를 지정합니다.

API 문서는 호출 호스트의 엔드포인트 이름을 기준으로 분류합니다. 예를 들어 위 API는 BCS 카테고리에서 확인할 수 있습니다. 다른 API는 API 인덱스에서 작업에 맞는 엔드포인트를 선택해 확인하세요.

기본 사용 흐름

액세스 키와 API 인증 토큰을 준비하고 요청 URL을 구성한 후, 서비스 API를 호출하여 응답을 확인합니다.

서비스 API 호출

토큰 발급 응답의 X-Subject-Token 값을 서비스 API 요청의 X-Auth-Token 헤더에 전달합니다. 다음은 인스턴스 유형 목록을 조회하는 예제입니다. {API_AUTH_TOKEN}을 발급받은 토큰으로 바꾸세요.

curl -X GET "https://bcs.kr-central-2.kakaocloud.com/api/v1/flavors" \
  -H "X-Auth-Token: {API_AUTH_TOKEN}"

다른 API를 호출할 때는 개별 API 문서의 메서드, 호출 URL과 필수 파라미터를 확인하세요. 필요한 작업은 API 인덱스에서 찾을 수 있습니다.

인증 정보 관리

API 인증 토큰의 권한은 보안 및 권한 관리를 위해 주기적으로 갱신되거나 변경될 수 있습니다. 따라서 필요한 작업을 수행하기 전에 토큰의 유효성을 확인하고 필요한 경우 새로운 토큰을 발급받아야 합니다.

안내

기본적으로 API 인증 토큰은 발급 후 12시간 이후 만료되며, 상황에 따라 12시간 이내라도 변경되거나 만료될 수 있습니다. 이 경우, 새로운 API 인증 토큰을 발급받아야 합니다.

API 인증 토큰의 권한은 아래 상황에 따라 변경되거나 만료될 수 있습니다.

경우	설명
권한 변경	소속 프로젝트 역할이 변경된 경우, 토큰 발급 시점과 현재 역할을 비교하여 일치하는 역할 또는 권한만 상속 - 프로젝트 관리자에서 프로젝트 멤버로 변경된 경우, 프로젝트 멤버 권한을 상속
권한 만료	다음 중 하나에 해당하는 경우 토큰 권한 만료 - 프로젝트 역할이 삭제(프로젝트에서 내보내기)된 경우 - 카카오클라우드 콘솔 > 우측 상단 프로필 > 자격 증명 메뉴에서 사용자가 액세스 키를 직접 삭제한 경우

API 호출 정보

API 호출 결과를 확인할 때 사용하는 공통 응답 코드입니다. 개별 API의 응답 스펙도 함께 확인하세요.

공통 응답 코드

다음은 API 요청에 대한 공통 응답 코드입니다.

성공 응답

HTTP 상태 코드	상태 텍스트	설명
200	OK	요청이 성공적으로 처리되었습니다.
201	Created	요청이 성공적으로 처리되어 새로운 리소스가 생성되었습니다.
202	Accepted	요청이 수락되었으며, 비동기적으로 처리됩니다.
204	No Content	요청이 성공했으나, 반환할 데이터가 없습니다.

오류 응답

HTTP 상태 코드	상태 텍스트	설명
400	Bad Request	요청 형식이 잘못되었습니다.
401	Unauthorized	인증되지 않은 사용자입니다. 유효한 인증 정보가 필요합니다.
403	Forbidden	해당 리소스에 접근할 권한이 없습니다.
404	Not Found	요청한 리소스를 찾을 수 없습니다.
409	Conflict	요청이 현재 서버 상태와 충돌합니다. (예: 리소스 중복 생성)
500	Internal Server Error	서버 내부 오류가 발생했습니다.

오류 응답은 일반적으로 다음과 같은 형식으로 반환됩니다.

오류 응답 예시
{
    "error": {
        "code": "string",
        "message": "string"
    }
}

API 작업 이력 확인

Cloud Trail에서 OpenAPI를 통해 수행한 작업의 이벤트와 요청 정보를 확인할 수 있습니다. 조회할 수 있는 이벤트는 서비스별 이벤트 목록을 참고하세요.

API 호출 이력은 카카오클라우드 콘솔 > Cloud Trail > 이벤트 메뉴에서 확인할 수 있으며, 이벤트 이름, 서비스 이름(OpenAPI), 리소스 유형 등을 기준으로 검색할 수 있습니다. OpenAPI 호출 이벤트의 서비스 이름은 OpenAPI이며, 실제 서비스 호출 이벤트는 해당 서비스 이름으로 표시됩니다. 조회 방법은 이벤트 조회를 참고하세요.

API 인덱스: 호출 호스트와 리소스별 API 찾기
API 변경 사항: API 추가·변경·삭제 내역
Cloud Trail 이벤트 목록: API 작업 이력에서 확인할 수 있는 서비스별 이벤트

API 사용 준비​

액세스 키 발급​

API 인증 토큰 발급​

방법 1: 액세스 키 ID로 발급​

방법 2: 액세스 키 이름으로 발급​

API 요청 구성​

기본 사용 흐름​

서비스 API 호출​

인증 정보 관리​

API 호출 정보​

공통 응답 코드​

성공 응답​

오류 응답​

API 작업 이력 확인​

관련 문서​