Getting started with OpenAPI

KakaoCloud APIs (Application Programming Interfaces) are interfaces that let you programmatically access and interact with KakaoCloud services, such as Beyond Compute Service (BCS) and Networking.

KakaoCloud OpenAPI list

KakaoCloud currently provides the following OpenAPI service categories.

• Beyond Compute Service: APIs for managing instances and operating compute resources
• Networking: APIs for creating, retrieving, updating, and deleting network resources
• Container Pack: APIs for configuring and managing container runtime environments
• Data Store: APIs that provide fully managed database services

Prerequisites

Before using KakaoCloud APIs, complete the following prerequisites.

Issue an access key

An IAM access key, which is an IAM user credential, consists of an IAM access key ID and a secret access key. This information is required to issue an API authentication token. The access key is granted permissions based on the IAM role assigned to the project selected when the key is issued.

You can issue or view IAM access keys in KakaoCloud Console > profile in the upper-right corner > Credentials > IAM Access Key. Secret access keys can be viewed only when the access key is created, so store them separately in a secure location.

Issue an API authentication token

To use APIs, you must issue an API authentication token. An API authentication token authenticates the user and grants permission to access APIs instead of using a user ID and password. You can authenticate with an API authentication token in the CLI or API and use KakaoCloud services.

There are two ways to issue an API authentication token, depending on the parameter configuration.

Type	Required parameters
API authentication token issuance method 1	IAM access key ID, secret access key
API authentication token issuance method 2	IAM access key name, secret access key, user unique ID

info

Before issuing an API authentication token, you must issue an access key.

caution

• When issuing an API authentication token, you must set the Request Header Content-Type value to application/json.
• Requests that do not include Content-Type: application/json in the Request Header will not issue an authentication token.

Method 1: Issue with access key ID

The first method for issuing an API authentication token uses the IAM access key ID and secret access key. Follow these steps.

1. After issuing an access key by referring to Issue an access key, enter the following path in the POST URL.

   API authentication token issuance URL

   https://iam.kakaocloud.com/identity/v3/auth/tokens

2. When requesting an authentication token, include Content-Type in the Request Header as follows.

   Key	Value	Required	Description
   Content-Type	application/json	Required	Specifies that the data in the request body is in JSON format

3. Add the following code to the JSON body and enter the required parameters.

   API authentication token issuance method 1

   {
       "auth": {
           "identity": {
               "methods": [
                   "application_credential"
               ],
               "application_credential": {
                   "id": "${IAM access key ID}",
                   "secret": "${Secret access key}"
               }
           }
       }
   }

   환경변수	설명
   IAM access key ID🖌︎	Can be viewed when the access key is created or by selecting the access key item in the access key list
   Secret access key🖌︎	Can be viewed only when the access key is created

   Parameter	Required	Description
   id	Required	IAM access key ID - Can be viewed when the access key is created or by selecting the access key in the access key list
   secret	Required	Secret access key - Can be viewed only when the access key is created

4. Check the issued API authentication token in the X-Subject-Token item of the response header.

   API authentication token issuance method 1 curl example

   curl -i -X POST "https://iam.kakaocloud.com/identity/v3/auth/tokens" \
   -H "Content-Type: application/json" \
   -d '{
       "auth": {
           "identity": {
               "methods": [
                   "application_credential"
               ],
               "application_credential": {
                   "id": "{IAM_ACCESS_KEY_ID}",
                   "secret": "{SECRET_ACCESS_KEY}"
               }
           }
       }
   }'

Method 2: Issue with access key name

The second method for issuing an API authentication token uses the IAM access key name, secret access key, and user unique ID. Follow these steps.

1. After issuing an access key, enter the following path in the POST URL.

   API authentication token issuance URL

   https://iam.kakaocloud.com/identity/v3/auth/tokens

2. When requesting an authentication token, include Content-Type in the Request Header as follows.

   Key	Value	Required	Description
   Content-Type	application/json	Required	Specifies that the data in the request body is in JSON format

3. Add the following code to the JSON body and enter the required parameters.

   API authentication token issuance method 2

   {
       "auth": {
           "identity": {
               "methods": [
                   "application_credential"
               ],
               "application_credential": {
                   "name": "${IAM access key name}",
                   "secret": "${Secret access key}",
                   "user": {
                       "id": "${User unique ID}"
                   }
               }
           }
       }
   }

   환경변수	설명
   IAM access key name🖌︎	KakaoCloud Console > profile in the upper-right corner > Credentials > IAM Access Key
   Secret access key🖌︎	Can be viewed only when the access key is created
   User unique ID🖌︎	KakaoCloud Console > User Profile > Account Information

   Item	Required	Description
   name	Required	IAM access key name (the value you entered) - Can be viewed in KakaoCloud Console > profile in the upper-right corner > Credentials > IAM Access Key
   secret	Required	Secret access key - Can be viewed only when the access key is created
   user.id	Required	User unique ID - Can be viewed in KakaoCloud Console > User Profile > Account Information

4. Check the issued API authentication token in the X-Subject-Token item of the response header.

   API authentication token issuance method 2 curl example

   curl -i -X POST "https://iam.kakaocloud.com/identity/v3/auth/tokens" \
   -H "Content-Type: application/json" \
   -d '{
       "auth": {
           "identity": {
               "methods": [
                   "application_credential"
               ],
               "application_credential": {
                   "name": "{IAM_ACCESS_KEY_NAME}",
                   "secret": "{SECRET_ACCESS_KEY}",
                   "user": {
                       "id": "{USER_ID}"
                   }
               }
           }
       }
   }'

API authentication token permission changes and expiration

API authentication token permissions may be periodically refreshed or changed for security and permission management. Before performing required tasks, check token validity and issue a new token if needed.

info

By default, API authentication tokens expire 12 hours after issuance. Depending on the situation, they may change or expire within 12 hours. In this case, issue a new API authentication token.

API authentication token permissions may change or expire in the following cases.

Case	Description
Permission change	If the project role changes, only matching roles or permissions are inherited by comparing the role at token issuance with the current role - If the role changes from Project Admin to Project Member, Project Member permissions are inherited
Permission expiration	Token permissions expire in any of the following cases - The project role is deleted (the user is removed from the project) - The user directly deletes the access key in KakaoCloud Console > profile in the upper-right corner > Credentials

List projects

In KakaoCloud, resources are managed by project. API permissions are determined by the project selected when the access key is issued and by the user's project role. The project ID is used in some API requests or responses to identify which project a resource belongs to. To list the projects that a user belongs to, follow this method.

Request

List projects request syntax

curl -X GET "https://iam.kakaocloud.com/identity/v3/users/{USER_ID}/projects" \
-H "X-Auth-Token: {API_AUTH_TOKEN}"

Type	Parameter	Format	Description
URL	{USER_ID}*	String	User unique ID - Can be checked in Console > profile in the upper-right corner > Account Information > ID
Header	{API_AUTH_TOKEN}*	String	API authentication token

Response

Field	Format	Description
projects	Array	Project list
projects.id	String	Unique identifier of the project (project ID)
projects.name	String	Project name
projects.domain_id	String	Unique identifier of the domain to which the project belongs (domain ID)
projects.description	String	Project description
projects.enabled	Boolean	Whether the project is enabled - true: The project is enabled - false: The project is not enabled
projects.parent_id	String	Unique identifier of the parent project (project parent ID)
projects.is_domain	Boolean	Whether the project is a domain - true: The project is a domain project - false: The project is not a domain project
projects.tags	Array	List of tags for the project
projects.options	Object	Additional option information for the project
projects.links	Object	Link information for the project
projects.links.self	String	Self-referential link for the current project

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

Common response codes

The following are common response codes for API requests.

Success responses

HTTP status code	Status text	Description
200	OK	The request was processed successfully.
201	Created	The request was processed successfully and a new resource was created.
202	Accepted	The request was accepted and will be processed asynchronously.
204	No Content	The request succeeded, but there is no data to return.

Error responses

HTTP status code	Status text	Description
400	Bad Request	The request format is invalid.
401	Unauthorized	The user is not authenticated. Valid authentication information is required.
403	Forbidden	You do not have permission to access the resource.
404	Not Found	The requested resource could not be found.
409	Conflict	The request conflicts with the current server state. (Example: duplicate resource creation)
500	Internal Server Error	An internal server error occurred.

Error responses are generally returned in the following format.

Error response example

{
    "error": {
        "code": "string",
        "message": "string"
    }
}

Check API activity history

All API call history performed through KakaoCloud OpenAPI is recorded as events in Cloud Trail. You can use these events to track activity history and request information, such as resource creation, modification, and deletion.

You can check API call history in KakaoCloud Console > Cloud Trail > Events and search by event name, service name (OpenAPI), resource type, and other criteria. For details about service-specific events generated by API calls, see OpenAPI-based event list.