API Preparations

This document describes the necessary information required to utilize APIs provided by KakaoCloud.

Create access key

An access key, which is required to get an API authentication token, is comprised of an access key ID and a secret access key. The permissions of an access key is decided by IAM roles assigned within a selected project. For details, please refer to Create access key.

Get API authentication token

An API authentication token replaces your KakaoCloud account ID and password, allowing you to use CLI or APIs to access KakaoCloud services. You can get the API authentication token as follows.

Type	Required parameters
Method 1. Get API authentication token	Access key ID, Secret access key
Method 2. Get API authentication token	Access key name, Secret access key, Unique user ID

info

Prior to obtaining the API authentication token, you need to create an access key beforehand.
By default, API authentication tokens expire 12 hours after issuance, and they may change or expire within 12 hours depending on the situation.

Method 1. Get API authentication token

You can obtain an API authentication token by using Access key ID and Secret access key as follows.

After getting an access key, enter the following POST URL.
Getting API authentication token
```
https://iam.kakaocloud.com/identity/v3/auth/tokens
```

Insert the code below into the JSON body of your request and fill in the required information.

Method 1 Request body
{
  "auth": {
    "identity": {
      "methods": ["application_credential"],
      "application_credential": {
        "id": "Access key ID",
        "secret": "Secret access key"
      }
    }
  }
}

Parameter	Required	Description
id	Required	Access key ID - Can be viewed at the time of creating the access key or in the access key list
secret	Required	Secret access key - Can only be viewed at the time of creating the access key

Check the API authentication token in the X-Subject-Token field within the response header.

Method 2. Get API authentication token

You can also get an API authentication token as an alternative by using Access key name, Secret access key, Unique user ID.

After getting an access key, enter the following POST URL.
Getting API authentication token
```
https://iam.kakaocloud.com/identity/v3/auth/tokens
```

Insert the code below into the JSON body of your request and fill in the required information.

Method 2 Request body
{
  "auth": {
    "identity": {
      "methods": ["application_credential"],
      "application_credential": {
        "name": "Name of access key",
        "secret": "Secret access key",
        "user": {
          "id": "unique user ID"
        }
      }
    }
  }
}

Parameter	Required	Description
name	Yes	Access key name(the value you entered) - Can be viewed in KakaoCloud Console > Account Settings > Access keys tab
secret	Yes	Secret access key - Can be viewed only at the time of creating an access key
user.id	Yes	Unique user ID - Can be viewed in Account Settings > Account Info tab

Check the API authentication token in the X-Subject-Token field within the response header.

Changes or expiration of API authentication token permissions

info

By default, API authentication tokens expire 12 hours after issuance, and they may change or expire within 12 hours depending on the situation. In such cases, a new token must be issued.

The permissions of API authentication tokens can be periodically renewed or changed for security purposes. Therefore, users must verify the validity of the token before performing necessary tasks and obtain a new token. The permissions of API authentication tokens may change or expire under the following circumstances.

Case	Description
Changes in permissions	If the role within the involved project changes, the token will inherit only the roles or permissions that match those at the time of token issuance and current roles - e.g. If a user changes from Project Admin to Project Member, the user's API authentication token will inherit the permissions of a Project Member.
Expired permissions	Case 1. If the project role is removed (deleted from the project) Case 2. If the user deletes his/her access key in KakaoCloud Console > Profile(Top right) > Access key menu.

Appendix. View project list

In KakaoCloud, resources are organized and managed on a per-project basis. You can check all projects with which you are associated as follows.

Request

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

Type	Parameter	Format	Required	Description
Header	`{tokenId}`	String	Yes	Token ID
URL	`{userId}`	String	Yes	Unique user ID - Can be found in Web Console > Right Profile > Account Info

Response

Response Example
{
  "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
  }
}

Appendix. Delete access key

You can delete access keys that are no longer needed.

caution

When a access key is deleted, the API authentication token automatically expires and can no longer be used.

Re-enter your password and click the [Confirm password] button.
In the Access key tab, click the [Delete] button for the access key you want to remove.

In the popup window, click the [Delete] button.
Verify that the access key has been removed.

Create access key​

Get API authentication token​

Method 1. Get API authentication token​

Method 2. Get API authentication token​

Changes or expiration of API authentication token permissions​

Appendix. View project list​

Request​

Response​

Appendix. Delete access key​