본문으로 건너뛰기

OpenAPI 시작하기

카카오클라우드 API(Application Programming Interface)는 카카오클라우드 서비스의 주요 구성 요소이며, Beyond Compute Service(BCS), Beyond Networking Service(BNS) 등의 서비스에서 프로그래밍 방식으로 액세스하고 상호 작용할 수 있는 인터페이스입니다.
카카오클라우드 API를 통해 카카오클라우드의 다양한 서비스를 프로그래밍적으로 제어하고 관리할 수 있습니다.

카카오클라우드 OpenAPI 목록​

현재 KakaoCloud가 제공하는 OpenAPI 목록은 다음과 같습니다.

사전 작업​

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

액세스 키 발급​

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

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

API 인증 토큰 발급​

API를 사용하려면 'API 인증 토큰'을 발급받아야 합니다. API 인증 토큰은 사용자 ID와 비밀번호를 대신하여 사용자를 인증하고 API에 접근할 수 있는 권한을 부여합니다.

CLI나 API에서 API 인증 토큰을 사용하여 인증하고, 카카오클라우드 서비스를 이용할 수 있습니다.
API 인증 토큰을 발급받는 방법은 파라미터 구성에 따라 두 가지 방식으로 구분됩니다.

구분필요한 파라미터
API 인증 토큰 발급 방법 1   IAM 액세스 키 ID, 보안 액세스 키
API 인증 토큰 발급 방법 2IAM 액세스 키의 이름, 보안 액세스 키, 사용자 고유 ID
안내
  • API 인증 토큰을 발급받기 위해서는 액세스 키 발급이 선행되어야 합니다.
  • 기본적으로 API 인증 토큰은 12시간 이후 만료되며, 상황에 따라 12시간 이내라도 변경되거나 만료될 수 있습니다.

API 인증 토큰 발급 방법 1​

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

  1. 액세스 키 발급을 참고하여 액세스 키를 발급받은 후, POST URL에 다음 경로를 입력합니다.

    API 인증 토큰 발급 URL
    https://iam.kakaocloud.com/identity/v3/auth/tokens

  2. JSON Body에 다음의 코드를 추가하고, 필요한 파라미터를 입력합니다.

    API 인증 토큰 발급 방법 1
    {
        "auth": {
            "identity": {
                "methods": [
                    "application_credential"
                ],
                "application_credential": {
                    "id": "${IAM 액세스 키 ID}",
                    "secret": "${보안 액세스 키}"
                }
            }
        }
    }
    환경변수설명
    IAM 액세스 키 ID🖌︎액세스 키 생성 시점 또는 액세스 키 목록에서 해당 액세스 키 항목을 클릭하여 조회 가능
    보안 액세스 키🖌︎액세스 키 생성 시점에만 조회 가능
    파라미터필수 여부설명
    id필수  IAM 액세스 키 ID
    - 액세스 키 생성 시점 또는 액세스 키 목록에서 해당 액세스 키를 클릭하여 조회 가능
    secret필수  보안 액세스 키
    - 액세스 키 생성 시점에만 조회 가능

  3. 응답받은 Response Header의 X-Subject-Token 항목에서 발급된 API 인증 토큰을 확인합니다.

API 인증 토큰 발급 방법 2​

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

  1. 액세스 키를 발급받은 후, POST URL에 https://iam.kakaocloud.com/identity/v3/auth/tokens를 입력합니다.

    API 인증 토큰 발급 URL
    https://iam.kakaocloud.com/identity/v3/auth/tokens

  2. JSON Body에 아래 코드를 추가하고, 필요한 파라미터를 입력합니다.

    API 인증 토큰 발급 방법 2
    {
        "auth": {
            "identity": {
                "methods": [
                    "application_credential"
                ],
                "application_credential": {
                    "name": "${IAM 액세스 키 이름}",
                    "secret": "${보안 액세스 키}",
                    "user": {
                        "id": "${사용자 고유 ID}"
                    }
                }
            }
        }
    }
    환경변수설명
    IAM 액세스 키 이름🖌︎카카오클라우드 콘솔 > 우측 상단 사용자 프로필 > 액세스 키에서 조회 가능
    보안 액세스 키🖌︎액세스 키 생성 시점에만 조회 가능
    사용자 고유 ID🖌︎카카오클라우드 콘솔 > 사용자 프로필 > 계정 정보에서 조회 가능
    항목필수 여부설명
    name필수  IAM 액세스 키의 이름(직접 입력한 값)
    - 카카오클라우드 콘솔 > 우측 상단 프로필 > 액세스 키에서 조회 가능
    secret필수  보안 액세스 키
    - 액세스 키 생성 시점에만 조회 가능
    user.id필수  사용자 고유 ID
    - 카카오클라우드 콘솔 > 사용자 프로필 > 계정 정보에서 조회 가능

  3. 응답받은 Response Header의 X-Subject-Token 항목에서 발급된 API 인증 토큰을 확인할 수 있습니다.

API 인증 토큰의 권한 변경/만료​

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

안내

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

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

경우설명
권한 변경소속 프로젝트 역할이 변경된 경우, 토큰 발급 시점과 현재 역할을 비교하여 일치하는 역할 또는 권한만 상속
- 예시: 프로젝트 관리자 → 프로젝트 멤버로 변경될 경우: 프로젝트 멤버 권한을 상속받음
권한 만료Case 1. 프로젝트 역할이 삭제(프로젝트에서 내보내기)된 경우
Case 2. 콘솔 > 우측 상단 프로필 > 액세스 키 항목에서 사용자가 액세스 키를 직접 삭제한 경우

공통 응답 코드​

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

성공 응답​

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

오류 응답​

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

프로젝트 목록 조회​

카카오클라우드에서는 프로젝트(Project) 단위로 리소스를 관리합니다. 사용자가 속한 프로젝트 목록을 조회하는 방법은 다음과 같습니다.

Request​
프로젝트 목록 조회 Request Syntax
curl -X GET "https://iam.kakaocloud.com/identity/v3/users/{userId}/projects" \
-H "X-Auth-Token: {tokenId}"
종류파라미터형식설명
URL{userId}*String사용자 고유 ID
- 콘솔 > 우측 상단 프로필 > 계정 정보에서 확인 가능
Header{tokenId}*   StringAPI 인증 토큰
Response​
필드형식설명
projectsArray프로젝트 목록
projects.idString프로젝트의 고유 식별자(프로젝트 ID)
projects.nameString프로젝트 이름
projects.domain_idString프로젝트가 속한 도메인의 고유 식별자(도메인 ID)
projects.descriptionString프로젝트 설명
projects.enabledBoolean프로젝트 허용 여부
- true: 프로젝트를 허용
- false: 프로젝트를 허용하지 않음
projects.parent_idString상위 프로젝트의 고유 식별자(프로젝트 parent ID)
projects.is_domainBoolean도메인 여부
- true: 프로젝트가 도메인 프로젝트인 경우
- false: 도메인 프로젝트가 아닌 경우
projects.tagsArray프로젝트에 대한 태그 목록
projects.optionsObject프로젝트에 대한 추가 옵션 정보
projects.linksObject프로젝트에 대한 링크 정보
projects.links.selfString현재 프로젝트에 대한 자기 참조 링크
프로젝트 목록 조회 Response
{
    "projects": [
        {
            "id": "ca7f6c731a004091a32d4eb97ec17271",
            "name": "KakaoCloud-project",
            "domain_id": "327373ec52974577a79a5e26b26c27e9",
            "description": "Kakao i Cloud-project",
            "enabled": true,
            "parent_id": "327373ec52974577a79a5e26b26c27e9",
            "is_domain": false,
            "tags": [],
            "options": {},
            "links": {
                "self": "http://iam.kakaocloud.com/v3/projects/ca7f6c731a004091a32d4eb97ec17271"
            }
        }
    ],
    "links": {
        "next": null,
        "self": "http://iam.kakaocloud.com/v3/users/f61e7df2a1d349e7b35d62ef9c615853/projects",
        "previous": null
    }
}