본문으로 건너뛰기

API 사용 준비

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

액세스 키 발급​

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

API 인증 토큰 발급​

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

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

API 인증 토큰 발급 방법 1​

API 인증 토큰을 발급받는 첫 번째 방법에서는 액세스 키 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": "액세스 키 ID",
                    "secret": "보안 액세스 키"
                }
            }
        }
    }
    항목필수 여부설명
    id필수  액세스 키 ID
    - 액세스 키 생성 시점 또는 액세스 키 목록에서 해당 액세스 키 항목을 클릭하여 조회 가능 &nbsp &nbsp
    secret필수  보안 액세스 키
    - 액세스 키 생성 시점에만 조회 가능

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

API 인증 토큰 발급 방법 2​

API 인증 토큰을 발급받는 두 번째 방법에서는 액세스 키의 이름, 보안 액세스 키, 사용자 고유 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": "액세스 키의 이름",
                    "secret": "보안 액세스 키",
                    "user": {
                        "id": "사용자 고유 ID"
                    }
                }
            }
        }
    }
    항목필수 여부설명
    name필수  액세스 키의 이름(직접 입력한 값)
    - Account Settings > 액세스 키 탭에서 조회 가능
    secret필수  보안 액세스 키
    - 액세스 키 생성 시점에만 조회 가능
    user.id필수  사용자 고유 ID
    - Account Settings > 계정 정보 탭에서 조회 가능

  3. 응답받은 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 인증 토큰은 자동으로 만료되며 더 이상 사용할 수 없습니다.

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

    이미지. 카카오클라우드 콘솔 카카오클라우드 콘솔

  2. 비밀번호를 다시 입력하고, [비밀번호 확인] 버튼을 클릭합니다.

  3. 액세스 키 탭에서 삭제할 액세스 키에 대해 [삭제] 버튼을 클릭합니다.

    이미지. 액세스 키 삭제 액세스 키 삭제

  4. 액세스 키 삭제 팝업창에서 [삭제] 버튼을 클릭합니다.

  5. 액세스 키가 삭제되었는지 확인합니다.

최종 수정: 에