Skip to main content

API User Guide

KakaoCloud APIs let you call and manage KakaoCloud services such as Beyond Compute Service (BCS) and Networking in code. Before calling an API, identify the API and endpoint to use, then issue an API authentication token with an IAM access key.

Find the API you need in the API Index. Select an endpoint to view its request host, primary operations, and related APIs. If a resource such as a public IP or volume is provided across multiple endpoints, use Select an endpoint for the operation to find the appropriate API.

Use the API Search field in the sidebar to quickly find API documentation by service name or API name.

Prepare to use the API​

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.

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

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.

    KeyValueRequiredDescription
    Content-Typeapplication/jsonRequired    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
    ParameterRequiredDescription
    idRequired  IAM access key ID
    - Can be viewed when the access key is created or by selecting the access key in the access key list
    secretRequired  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.

    KeyValueRequiredDescription
    Content-Typeapplication/jsonRequired    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
    ItemRequiredDescription
    nameRequired  IAM access key name (the value you entered)
    - Can be viewed in KakaoCloud Console > profile in the upper-right corner > Credentials > IAM Access Key
    secretRequired  Secret access key
    - Can be viewed only when the access key is created
    user.idRequired  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}"
                    }
                }
            }
        }
    }'

Configure an API request​

A request URL consists of an endpoint base URL and an API path. For example, Get instance type uses the following request URL:

GET https://bcs.kr-central-2.kakaocloud.com/api/v1/flavors/{flavor_id}

In this URL, bcs is the endpoint name, kr-central-2 is the region, and /api/v1/flavors/{flavor_id} is the API path. Replace {flavor_id} with the ID of the instance type to retrieve.

API documentation is grouped by the request endpoint. For example, this API is available under BCS.

VPC & Network endpoints

The VPC & Network sidebar item combines APIs from the related vpc and network endpoints. VPC, subnet, route table, and network interface APIs use the vpc host. Public IP and security group APIs use the network host. Before sending a request, check the endpoint distinction and the base URL in the individual API specification.

Basic workflow​

After preparing an access key and API authentication token, construct the request URL, call the service API, and verify the response.

Call a service API​

Pass the X-Subject-Token value from the token issuance response in the X-Auth-Token header of the service API request. The following example lists instance types. Replace {API_AUTH_TOKEN} with the issued token.

curl -X GET "https://bcs.kr-central-2.kakaocloud.com/api/v1/flavors" \
  -H "X-Auth-Token: {API_AUTH_TOKEN}"

For other APIs, verify the method, request URL, and required parameters in the individual API specification. Use API Index to find the operation you need.

Manage authentication information​

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.

CaseDescription
Permission changeIf 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 expirationToken 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

API request information​

These are the common response codes used when reviewing API call results. Also check the response specification for each API.

Common response codes​

The following are common response codes for API requests.

Success responses​

HTTP status codeStatus textDescription
200       OKThe request was processed successfully.
201Created     The request was processed successfully and a new resource was created.
202AcceptedThe request was accepted and will be processed asynchronously.
204No ContentThe request succeeded, but there is no data to return.

Error responses​

HTTP status codeStatus textDescription
400       Bad RequestThe request format is invalid.
401UnauthorizedThe user is not authenticated. Valid authentication information is required.
403ForbiddenYou do not have permission to access the resource.
404Not FoundThe requested resource could not be found.
409ConflictThe request conflicts with the current server state. (Example: duplicate resource creation)
500Internal Server ErrorAn 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​

You can review events and request information for operations performed through OpenAPI in Cloud Trail. See the Events by service for the events available in API activity history.

You can review API call history in KakaoCloud Console > Cloud Trail > Events and search by event name, service name (OpenAPI), and resource type. The service name for OpenAPI call events is OpenAPI; events from the actual service called are displayed under that service name. For details, see View events.