API 사용 준비

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

IAM 액세스 키 발급

IAM 사용자 자격 증명인 IAM 액세스 키(IAM access key)는 IAM 액세스 키 ID와 보안 액세스 키를 의미하며, API 인증 토큰 발급을 위해 필요한 정보입니다. IAM 액세스 키의 권한은 선택한 프로젝트의 IAM 역할에 따라 결정됩니다.
IAM 액세스 키는 콘솔 우측 상단의 프로필 항목에서 발급받을 수 있으며, 자세한 발급 절차는 자격 증명 > IAM 액세스 키 발급을 참고하시기 바랍니다.

API 인증 토큰 발급

안내

API 인증 토큰을 발급받기 위해서는 IAM 액세스 키 발급이 선행되어야 합니다.
기본적으로 API 인증 토큰은 12시간 이후 만료되며, 상황에 따라 12시간 이내라도 변경되거나 만료될 수 있습니다.

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

구분	필요한 파라미터
API 인증 토큰 발급 방법 1	IAM 액세스 키 ID, 보안 액세스 키
API 인증 토큰 발급 방법 2	IAM 액세스 키의 이름, 보안 액세스 키, 사용자 UUID

API 인증 토큰 발급 방법 1

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

IAM 액세스 키 발급을 참고하여 IAM 액세스 키를 발급받은 후, POST URL에 다음 경로를 입력합니다.
API 인증 토큰 발급 URL
```
https://iam.kakaocloud.com/identity/v3/auth/tokens
```

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

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

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

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

API 인증 토큰 발급 방법 2

API 인증 토큰을 발급받는 두 번째 방법에서는 IAM 액세스 키 이름, 보안 액세스 키, 사용자 UUID를 사용합니다.

IAM 액세스 키 발급을 참고하여 IAM 액세스 키를 발급받은 후, POST URL에 다음 경로를 입력합니다.
API 인증 토큰 발급 URL
```
https://iam.kakaocloud.com/identity/v3/auth/tokens
```

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

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

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

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

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

안내

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

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

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

부록. 프로젝트 목록 조회

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

Request

Request 예시
GET https://iam.kakaocloud.com/identity/v3/users/{userId}/projects
X-Auth-token: {tokenId}

종류	파라미터	형식	필수 여부	설명
Header	`{tokenId}`	String	필수	API 인증 토큰
URL	`{userId}`	String	필수	사용자 UUID - 카카오클라우드 콘솔 > 우측 상단 프로필 > 계정 정보에서 확인 가능

Response

Response 예시
{
    "projects": [
        {
            "id": "ca7f6c731a004091a32d4eb97ec17271",
            "name": "kakaocloud-project",
            "domain_id": "327373ec52974577a79a5e26b26c27e9",
            "description": "kakaocloud-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
    }
}

부록. IAM 액세스 키 삭제

IAM 액세스 키를 삭제하는 방법은 다음과 같습니다.

주의

IAM 액세스 키 삭제 시, API 인증 토큰은 자동으로 만료되며 더 이상 사용할 수 없습니다.

카카오클라우드 콘솔 우측 상단에 위치한 사용자 프로필에서 자격 증명를 선택합니다.

카카오클라우드 콘솔
비밀번호를 다시 입력하고, [비밀번호 확인] 버튼을 클릭합니다.
자격 증명 메뉴에서 삭제할 IAM 액세스 키를 선택하고 상단의 [삭제] 버튼을 클릭하거나, [더 보기] 아이콘에서 삭제를 클릭합니다.

IAM 액세스 키 삭제
팝업창에서 [삭제] 버튼을 클릭합니다.
IAM 액세스 키 목록에서 IAM 액세스 키가 삭제되었는지 확인합니다.

IAM 액세스 키 발급​

API 인증 토큰 발급​

API 인증 토큰 발급 방법 1​

API 인증 토큰 발급 방법 2​

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

부록. 프로젝트 목록 조회​

Request​

Response​

부록. IAM 액세스 키 삭제​