본문으로 건너뛰기

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
}
}