API 사용 준비

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

액세스 키 발급

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

API 인증 토큰 발급

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

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

안내

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

API 인증 토큰 발급 방법 1

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

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

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

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

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

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

API 인증 토큰 발급 방법 2

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

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

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

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

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

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

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

안내

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

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

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

부록. 프로젝트 목록 조회

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

Request

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

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

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

부록. 액세스 키 삭제

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

주의

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

카카오클라우드 콘솔 우측 상단에 위치한 프로필에서 액세스 키를 선택합니다.

카카오클라우드 콘솔
비밀번호를 다시 입력하고, [비밀번호 확인] 버튼을 클릭합니다.
액세스 키 메뉴에서 삭제할 액세스 키에 대해 [삭제] 버튼을 클릭합니다.

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

액세스 키 발급​

API 인증 토큰 발급​

API 인증 토큰 발급 방법 1​

API 인증 토큰 발급 방법 2​

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

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

Request​

Response​

부록. 액세스 키 삭제​