OpenAPI 시작하기
카카오클라우드 API(Application Programming Interface)는 카카오클라우드 서비스의 주요 구성 요소이며, Beyond Compute Service(BCS), Beyond Networking Service(BNS) 등의 서비스에서 프로그래밍 방식으로 액세스하고 상호 작용할 수 있는 인터페이스입니다.
카카오클라우드 API를 통해 카카오클라우드의 다양한 서비스를 프로그래밍적으로 제어하고 관리할 수 있습니다.
카카오클라우드 OpenAPI 목록
현재 KakaoCloud가 제공하는 OpenAPI 목록은 다음과 같습니다.
- Beyond Compute Service: 인스턴스 관리 및 컴퓨팅 자원 조작을 위한 API
- Beyond Networking Service: 네트워크 자원을 생성, 조회, 수정, 삭제할 수 있는 API
사전 작업
카카오클라우드에서 제공하는 API를 사용하기 위해 수행해야 하는 사전 작업은 다음과 같습니다.
액세스 키 발급
IAM 사용자 자격 증명인 액세스 키(Access key)는 액세스 키 ID와 보안 액세스 키를 의미하며, API 인증 토큰 발급을 위해 필요한 정보입니다.
발급 시 선택한 프로젝트에서 부여받은 IAM 역할에 따라 액세스 키의 권한이 주어집니다.
액세스 키는 카카오클라우드 콘솔 > 우측 상단 프로필 > 액세스 키에서 발급/조회할 수 있습니다.
API 엔드포인트 확인
API를 사용하기 위해 먼저 카카오클라우드 엔드포인트를 확인해야 합니다. 엔드포인트는 API 요청을 보낼 대상 서버의 주소를 나타냅니다.
서비스 | 엔드포인트 |
---|---|
Instance | https://bcs.kr-central-2.kakaocloud.com/api/v1/instances/ |
Key Pair | https://bcs.kr-central-2.kakaocloud.com/api/v1/keypairs/ |
Volume | https://volume.kr-central-2.kakaocloud.com/api/v1/volumes/ |
VPC | https://vpc.kr-central-2.kakaocloud.com/api/v1/vpcs/ |
Network | https://vpc.kr-central-2.kakaocloud.com/api/v1/network-interfaces/ |
Public IP | https://network.kr-central-2.kakaocloud.com/api/v1/public-ips/ |
Load Balancer | https://load-balancer.kr-central-2.kakaocloud.com/api/v1/load-balancers/ |
API 인증 토큰 발급
API를 사용하려면 'API 인증 토큰'을 발급받아야 합니다. API 인증 토큰은 사용자 ID와 비밀번호를 대신하여 사용자를 인증하고 API에 접근할 수 있는 권한을 부여합니다.
CLI나 API에서 API 인증 토큰을 사용하여 인증하고, 카카오클라우드 서비스를 이용할 수 있습니다.
API 인증 토큰을 발급받는 방법은 파라미터 구성에 따라 두 가지 방식으로 구분됩니다.
구분 | 필요한 파라미터 |
---|---|
API 인증 토큰 발급 방법 1 | 액세스 키 ID, 보안 액세스 키 |
API 인증 토큰 발급 방법 2 | 액세스 키의 이름, 보안 액세스 키, 사용자 고유 ID |
- API 인증 토큰을 발급받기 위해서는 액세스 키 발급이 선행되어야 합니다.
- 기본적으로 API 인증 토큰은 12시간 이후 만료되며, 상황에 따라 12시간 이내라도 변경되거나 만료될 수 있습니다.
API 인증 토큰 발급 방법 1
API 인증 토큰을 발급받는 첫 번째 방법에서는 액세스 키 ID와 보안 액세스 키를 사용합니다. 자세한 발급 방법은 다음과 같습니다.
-
액세스 키 발급을 참고하여 액세스 키를 발급받은 후,
POST
URL에 다음 경로를 입력합니다.API 인증 토큰 발급 URLhttps://iam.kakaocloud.com/identity/v3/auth/tokens
-
JSON Body에 다음의 코드를 추가하고, 필요한 파라미터를 입력합니다.
API 인증 토큰 발급 방법 1{
"auth": {
"identity": {
"methods": [
"application_credential"
],
"application_credential": {
"id": "${액세스 키 ID}",
"secret": "${보안 액세스 키}"
}
}
}
}환경변수 설명 액세스 키 ID🖌︎ 액세스 키 생성 시점 또는 액세스 키 목록에서 해당 액세스 키 항목을 클릭하여 조회 가능 보안 액세스 키🖌︎ 액세스 키 생성 시점에만 조회 가능 파라미터 필수 여부 설명 id 필수 액세스 키 ID
- 액세스 키 생성 시점 또는 액세스 키 목록에서 해당 액세스 키를 클릭하여 조회 가능secret 필수 보안 액세스 키
- 액세스 키 생성 시점에만 조회 가능 -
응답받은 Response Header의
X-Subject-Token
항목에서 발급된 API 인증 토큰을 확인합니다.
API 인증 토큰 발급 방법 2
API 인증 토큰을 발급받는 두 번째 방법에서는 액세스 키의 이름, 보안 액세스 키, 사용자 고유 ID를 사용합니다. 자세한 발급 방법은 다음과 같습니다.
-
액세스 키를 발급받은 후,
POST
URL에https://iam.kakaocloud.com/identity/v3/auth/tokens
를 입력합니다.API 인증 토큰 발급 URLhttps://iam.kakaocloud.com/identity/v3/auth/tokens
-
JSON Body에 아래 코드를 추가하고, 필요한 파라미터를 입력합니다.
API 인증 토큰 발급 방법 2{
"auth": {
"identity": {
"methods": [
"application_credential"
],
"application_credential": {
"name": "${액세스 키 이름}",
"secret": "${보안 액세스 키}",
"user": {
"id": "${사용자 고유 ID}"
}
}
}
}
}환경변수 설명 액세스 키 이름🖌︎ 카카오클라우드 콘솔 > 우측 상단 사용자 프로필 > 액세스 키에서 조회 가능 보안 액세스 키🖌︎ 액세스 키 생성 시점에만 조회 가능 사용자 고유 ID🖌︎ 카카오클라우드 콘솔 > 사용자 프로필 > 계정 정보에서 조회 가능 항목 필수 여부 설명 name 필수 액세스 키의 이름(직접 입력한 값)
- 카카오클라우드 콘솔 > 우측 상단 프로필 > 액세스 키에서 조회 가능secret 필수 보안 액세스 키
- 액세스 키 생성 시점에만 조회 가능user.id 필수 사용자 고유 ID
- 카카오클라우드 콘솔 > 사용자 프로필 > 계정 정보에서 조회 가능 -
응답받은 Response Header의
X-Subject-Token
항목에서 발급된 API 인증 토큰을 확인할 수 있습니다.
API 인증 토큰의 권한 변경/만료
API 인증 토큰의 권한은 보안 및 권한 관리를 위해 주기적으로 갱신되거나 변경될 수 있습니다. 따라서 필요한 작업을 수행하기 전에 토큰의 유효성을 확인하고 필요한 경우 새로운 토큰을 발급받아야 합니다.
기본적으로 API 인증 토큰은 발급 후 12시간 이후 만료되며, 상황에 따라 12시간 이내라도 변경되거나 만료될 수 있습니다. 이 경우, 새로운 API 인증 토큰을 발급받아야 합니다.
API 인증 토큰의 권한은 아래 상황에 따라 변경되거나 만료될 수 있습니다.
경우 | 설명 |
---|---|
권한 변경 | 소속 프로젝트 역할이 변경된 경우, 토큰 발급 시점과 현재 역할을 비교하여 일치하는 역할 또는 권한만 상속 - 예시: 프로젝트 관리자 → 프로젝트 멤버로 변경될 경우: 프로젝트 멤버 권한을 상속받음 |
권한 만료 | Case 1. 프로젝트 역할이 삭제(프로젝트에서 내보내기)된 경우 Case 2. 콘솔 > 우측 상단 프로필 > 액세스 키 항목에서 사용자가 액세스 키를 직접 삭제한 경우 |
프로젝트 목록 조회
카카오클라우드에서는 프로젝트(Project) 단위로 리소스를 관리합니다. 사용자가 속한 프로젝트 목록을 조회하는 방법은 다음과 같습니다.
Request
curl -X GET "https://iam.kakaocloud.com/identity/v3/users/{userId}/projects" \
-H "X-Auth-Token: {tokenId}"
종류 | 파라미터 | 형식 | 설명 |
---|---|---|---|
URL | {userId} * | String | 사용자 고유 ID - 콘솔 > 우측 상단 프로필 > 계정 정보에서 확인 가능 |
Header | {tokenId} * | String | API 인증 토큰 |
Response
필드 | 형식 | 설명 |
---|---|---|
projects | Array | 프로젝트 목록 |
projects.id | String | 프로젝트의 고유 식별자(프로젝트 ID) |
projects.name | String | 프로젝트 이름 |
projects.domain_id | String | 프로젝트가 속한 도메인의 고유 식별자(도메인 ID) |
projects.description | String | 프로젝트 설명 |
projects.enabled | Boolean | 프로젝트 허용 여부 - true : 프로젝트를 허용 - false : 프로젝트를 허용하지 않음 |
projects.parent_id | String | 상위 프로젝트의 고유 식별자(프로젝트 parent ID) |
projects.is_domain | Boolean | 도메인 여부 - true : 프로젝트가 도메인 프로젝트인 경우- false : 도메인 프로젝트가 아닌 경우 |
projects.tags | Array | 프로젝트에 대한 태그 목록 |
projects.options | Object | 프로젝트에 대한 추가 옵션 정보 |
projects.links | Object | 프로젝트에 대한 링크 정보 |
projects.links.self | String | 현재 프로젝트에 대한 자기 참조 링크 |
{
"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
}
}