Bucket

You can use Object Storage's Bucket API to create buckets and manage related information and policies.

API preparations

Please refer to the API Preparation for the preparatory work required to call the API.
For a description of the API model of Object Storage, please refer to the API model.

API endpoint

The Object Storage API endpoint is as follows:

Object Storage API endpoint format

https://objectstorage.kr-central-2.kakaocloud.com

Create bucket

You can create a bucket.

info

According to KakaoCloud IAM role, the Project Admin or Project Member role is required to create a bucket.

Request Syntax

Request Syntax
curl --request PUT --location 'https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data '{
  "name": "my-bucket-new",
  "type": "STANDARD",
  "use_encryption": true,
  "encryption_configuration": {
    "type": "managed"
  }
}'

API method

Method	Request URL
PUT	`https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket`

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Enter authentication token
Content-Type	String	Required	Fixed with `application/json`

Request Elements

Request	Type	Required or not	Description
name	String	Required	Bucket name
type	String	Required	Bucket type - `Standard` (default): standard bucket
use_encryption	Boolean	Select	Whether to encrypt the bucket If you enter the `encryption_configuration` setting, the input value will be ignored - `false` (default): Do not encrypt - `true`: Encrypt (same as encryption_configuration.type = managed)
encryption_configuration ▼	Structure	Select	Set up bucket encryption
type	String	Required	Encryption method - `managed` (default): Automatic encryption provided by Saba - `true` (to be supported): Encryption linked to key management service using KMS

Response Syntax

Response Syntax
{
   "account": "project-id",
   "project": "project-id",
   "name": "my-bucket-new",
   "type": "STANDARD",
   "bytes": 0,
   "objectCount": 0,
   "createdAt": "2022-04-25T10:28:57Z",
   "acl": {
     "permissions": null,
     "public": "read-only",
     "public_read_allow_ip_list": [
       "ip / cidr"
     ]
   },
   "lastModified": "2022-04-25T10:28:57Z",
   "use_encryption": true,
   "encryption_type": "managed",
   "storageClass": "STANDARD",
   "storagePolicy": "default-placement"
}

Response Elements

Response	Type	Description
account (Deprecated)	String	Project ID - Account value in Swift API. - Can be confirmed when token is issued
project	String	Project ID
name	String	Created bucket name
type	String	Created bucket type - `STANDARD` (default): standard bucket
bytes	String	Total usage - Unit: Byte
objectCount	Int	Number of objects in bucket
createdAt	String	Creation date - Format: RFC3339 - Example: 2020-07-01T00:00:00Z
use_encryption	Boolean	Whether to encrypt bucket - `false` (default): Do not encrypt - `true`: Encrypt
encryption_type	String	Bucket encryption type
lastModified	String	Last modified - Format: RFC3339 - Example: 2020-07-01T00:00:00Z
storageClass	String	Storage class type - `STANDARD` (default): bucket of class standard
storagePolicy	String	Zone of storage class - `default-placement`
acl ▼	-	Access rights to bucket - When `null` is entered, existing ACL settings are deleted
public	String	Whether to allow public access - `read-only`, `deny`
public_read_allow_ip_list	List	List of IPs allowed for public access

Status Code

HTTP Status	Response	Description
`200`	OK	Success
`400`	Bad Request	Input setting error
`401`	Unauthorized	No permission
`409`	Conflicts	Creation failed - Same `bucket_name` already exists

Manage bucket

View bucket details

If you have storage.buckets.get permission, you can view detailed information about a specific bucket. For detailed permissions of Object Storage, please refer to Manage permission.

Request Syntax

Request Syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'

API method

Method	Request URL
GET	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/{bucket_name}`

Path	Type	Required or not	Description
region_name	String	Required	Region name
bucket_name	String	Required	Bucket name

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Enter authentication token

Response Syntax

For a details of Bucket's API model, please refer to Bucket API model.

Response Syntax
{    
    "project": "project-id",    
    "name": "test-bucket-01",    
    "type": "STANDARD",    
    "bytes": 0,    
    "objectCount": 0,    
    "createdAt": "2023-06-21T07:17:10Z",    
    "use_encryption": true,    
    "encryption_type": " ",    
    "lastModified": "2023-06-21T07:17:10Z",    
    "storageClass": "STANDARD",    
    "storagePolicy": "default-placement",    
    "acl": {        
        "public": "deny",        
        "public_read_allow_ip_list": null    
    }
} 

Response Elements

Response	Type	Description
project	String	Project ID - Able to get this information when issuing a token - Used in S3 API
name	String	Created bucket name
type	String	Created bucket type - `standard` (default): standard bucket
bytes	String	Total usage - Unit: Byte
objectCount	Int	Number of objects in bucket
createdAt	String	Creation date - Format: RFC3339 - Example: 2020-07-01T00:00:00Z
use_encryption	Boolean	Whether to encrypt bucket - `false` (default): Do not encrypt - `true`: Encrypt
encryption_type	String	Bucket encryption type
lastModified	String	Last modified - Format: RFC3339 - Example: 2020-07-01T00:00:00Z
storageClass	String	Storage class type (kr-central-2 only) - `standard` (default): Bucket of standard class
storagePolicy	String	Zone of storage class
acl ▼	-	Access rights to bucket - When `null` is entered, existing ACL settings are deleted
public	String	Read-only - Only `read-only` can be written
public_read_allow_ip_list	List	List of IPs allowed for public access

Status Code

HTTP Status	Response	Description
`200`	OK	Success
`400`	Bad Request	Input setting error
`401`	Unauthorized	Authentication failed
`403`	Forbidden	No permission

Query bucket list

You can view the bucket list.

info

According to KakaoCloud IAM role, the Project Admin or Project Member role is required to view the bucket.

Request Syntax

Request Syntax
curl --location --request GET 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket?limit=100' \
--header 'X-Auth-Token: {x-auth-token}'

API method

Method	Request URL
GET	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket`

Request Element

Path	Type	Required or not	Description
region_name	String	Required	Region name

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Authentication token

Request Query

Request	Type	Required or not	Description
offset	Query	Select	Retrieves n items from the bucket list starting from offset - Offsets start from 0 - Default: `0`
limit	Query	Select	Limit number of lists - Default value: `20` (up to 100 items can be viewed)
prefix	Query	Select	Search bucket name by prefix
include	Query	Select	Search bucket name by containing string - cannot be used with Prefix
type	Query	Select	Type search conditions - `STANDARD`
by	Query	Select	Sorting area - `bucket_name`: Bucket name - `bucket_type`: Type of bucket - `created_at`: Bucket last modified date - `bytes_used`: Usage of bucket
direct	Query	Select	Sort order - `asc`: Ascending (default) - `desc`: Descending

Response Syntax

Response Syntax
{
   totalCount: int
   offset: int
   count: int
   items: [SimpleBucket]
}  

Response Elements

Response	Type	Description
totalCount	Int	Total number of buckets
offset	Int	Retrieves n items from the bucket list starting from offset - from i to i+n
count	Int	Number of buckets returned
items	List	Bucket details - Model - Simple Bucket

Status Code

HTTP Status	Response	Description
`200`	OK	Success
`401`	Unauthorized	No permission to view (token error)
`403`	Forbidden	No viewing permission

Manage bucket access

You can manage access to buckets you own. You can apply public access or IP list-based access control to user-owned buckets with the following request.

Request Syntax

Request Syntax
curl --request POST --location 'https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'Content-Type: application/json' \
--data '{
 "name": "my-bucket-new",
 "acl": {
 "public": "read-only",
 "public_read_allow_ip_list": [
 "1.1.1.1",
 "2.2.2.0/24"
 ]
 }
}'

API method

Method	Request URL
POST	`https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}`

Path	Type	Required or not	Description
bucket_name	String	Required	Bucket name

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Authentication token
Content-Type	String	Required	Fixed with `application/json`

Request Elements

Request	Type	Required or not	Description
bucket_name	String	Required	Bucket name
acl ▼	Structure	Required	Access rights to bucket - When `null` is entered, existing ACL settings are deleted
public	String	Select	Whether to allow public access - `read-only`: Allowed - `deny`: Not allowed (same as acl = null)
public_read_allow_ip_list	List	Select	List of IPs that allow access

Response Syntax

Response Syntax
{
  "project": "0bc7a4c4a8fb4fee98dcf1936d8ed8eb",
  "account": "0bc7a4c4a8fb4fee98dcf1936d8ed8eb",
  "name": "my-bucket-new",
  "type": "STANDARD",
  "bytes": 0,
  "objectCount": 0,
  "createdAt": "2023-07-08T04:08:05Z",
  "use_encryption": true,
  "encryption_type": "managed",
  "lastModified": "2023-07-08T04:08:05Z",
  "storageClass": "STANDARD",
  "storagePolicy": "default-placement",
  "acl": {
    "public": "deny",
    "public_read_allow_ip_list": null
  }
}

Response Elements

Response	Type	Description
account (Deprecated)	String	Project ID - Can be confirmed when issuing a token
project	String	Project ID - Able to get this information when issuing a token
name	String	Created bucket name
type	String	Created bucket type - `STANDARD` (default): standard bucket
bytes	String	Total usage - Unit: Byte
objectCount	Int	Number of objects in bucket
createdAt	String	Creation date - Format: https://www.rfc-editor.org/rfc/rfc3339 - Example: 2020-07-01T00:00:00Z
use_encryption	Boolean	Whether to encrypt bucket - `false` (default): Do not encrypt - `true`: Encrypt
encryption_type	String	Bucket encryption type
lastModified	String	Last modified - Format: https://www.rfc-editor.org/rfc/rfc3339 - Example: 2020-07-01T00:00:00Z
storageClass	String	Storage class type - `STANDARD` (default): bucket of class standard
storagePolicy	String	Zone of storage class - `default-placement`
acl ▼	-	Access rights to bucket - When `null` is entered, existing ACL settings are deleted
public	String	Whether to allow public access - `read-only`, `deny`
public_read_allow_ip_list	List	List of IPs allowed for public access

Status Code

HTTP Status	Response	Description
`200`	OK	Success
`401`	Unauthorized	No permission (TOKEN error)
`403`	Forbidden	No edit permission
`404`	Not found	Bucket not found

S3 bucket access control

You can control bucket access using the S3 API.

Request Syntax
curl --request POST --location 'https://objectstorage.kr-central-2.kakaocloud.com/{bucket_name}?acl' \
--header 'Authorization: {authorization}' \
--header 'Content-Type: application/xml' \
--header 'x-amz-acl: {Acl}' \
--header 'Content-MD5: {ContentMD5}' \
--header 'x-amz-grant-full-control: {GrantFullControl}' \
--header 'x-amz-grant-read: {GrantRead}' \
--header 'x-amz-grant-read-acp: {GrantReadACP}' \
--header 'x-amz-grant-write: {GrantWrite}' \
--header 'x-amz-grant-write-acp: {GrantWriteACP}' \
--data '<?xml version="1.0" encoding="UTF-8"?>
<AccessControlPolicy xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <AccessControlList>
      <Grant>
         <Grantee>
            <ID>string</ID>
            <URI>string</URI>
         </Grantee>
         <Permission>string</Permission>
      </Grant>
   </AccessControlList>
</AccessControlPolicy>'

API method

Method	Request URL
POST	`https://objectstorage.kr-central-2.kakaocloud.com/{bucket_name}?acl`

Path	Type	Required or not	Description
bucket_name	String	Required	Bucket name

Request Header

Request	Type	Required or not	Description
Authorization	String	Required	S3 authorization header
Content-Type	String	Required	Type of body content - Input other than application/xml may result in a parsing error
x-amz-acl	String	Select	canned ACL to apply to bucket - `private` : public Not public. Remove all permissions except storage.owner - `public-read`: Grant storage.objectReader role to all users - `public-read-write`: Grant storage.objectCreator role to all users - `authenticated-read`: Grants the storage.objectReader role to users authorized on the project
Content-MD5	String	Required	128-bit MD5 of the body encrypted in base64
x-amz-grant-full-control	String	Select	Grant storage.admin role to specified user - Provide only user ID and AllUsers uri (`http://acs.amazonaws.com/groups/global/AllUsers`)
x-amz-grant-read	String	Select	Grant storage.objectReader role to specified user - Provide only user ID and AllUsers uri (`http://acs.amazonaws.com/groups/global/AllUsers`)
x-amz-grant-read-acp	String	Select	Grant storage.policyReader role to specified user - Provide only user ID and AllUsers uri (`http://acs.amazonaws.com/groups/global/AllUsers`)
x-amz-grant-write	String	Select	Grant storage.objectCreator role to specified user - Provide only user ID and AllUsers uri (`http://acs.amazonaws.com/groups/global/AllUsers`)
x-amz-grant-write-acp	String	Select	Grant storage.policyWriter role to specified user - Provide only user ID and AllUsers uri (`http://acs.amazonaws.com/groups/global/AllUsers`)

Request Elements

Request	Type	Required or not	Description
bucket_name	String	Required	Bucket name
AccessControlPolicy ▼	Structure	Select
AccessControlList ▼	Structure	Required	List of Access Controls to set for bucket
Grant ▼	List	Required
Grantee ▼	Structure	Required	Who will be granted permission
ID	String	Select	User ID - Input when granting permission to a user - One of `ID` and `URI` must be input
URI	String	Select	Input when granting permission to the AllUsers group - `http://acs.amazonaws.com/groups/global/AllUsers` - One of `ID` and `URI` must be input.
Permission	String	Required	Type of permission to grant - `FULL_CONTROL`: storage.admin role - `WRITE`: storage .objectCreator role - `WRITE-ACP`: storage.policyWriter role - `READ`: storage.objectReader role - `READ-ACP`: storage.policyReader role

Status Code

HTTP Status	Response	Description
`200`	OK	Success
`401`	Unauthorized	No permission (token error)
`403`	Forbidden	No edit permission
`404`	Not found	Bucket not found

Delete bucket

You can delete buckets that you own. To delete a bucket, storage.buckets.delete permission is required.

If objects exist within the bucket, the bucket cannot be deleted.

Request Syntax

Request Syntax
curl --location --request DELETE 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'

API method

Method	Request URL
DELETE	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}`

Request Element

Path	Type	Required or not	Description
region_name	String	Required	Region name
bucket_name	String	Required	Bucket name

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Authentication token

Response Syntax

Status Code

HTTP Status	Response	Description
`204`	No Content	Delete successful
`401`	Unauthorized	Authentication failed
`404`	Not found	Bucket not found
`409`	Conflict	Bucket is not empty

Empty bucket

If you have storage.objects.delete permission, you can delete all objects under the bucket by emptying the bucket. For detailed permissions of Object Storage, please refer to Manage permission.

Request Syntax

Request Syntax
curl --location --request DELETE 'https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/?dir-delete' \
--header 'X-Auth-Token: {X-Auth-Token}'

API method

Method	Request URL
DELETE	`https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/?dir-delete`

Path	Type	Required or not	Description
account	String	Required	Project ID - Able to get this information when issuing a token - Used as the account value in Swift API
directory	String	Select	The name of the directory whose child objects to delete

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Authentication token

Response Syntax

Status Code

HTTP Status	Response	Description
`200`	OK	Success
`400`	Bad Request	Bad request (bad name convention or non-existent)
`401`	Unauthorized	Authentication failed
`403`	Forbidden	No permission

Empty bucket folder

If you have storage.objects.delete permission, you can delete all objects under the specified path by emptying the bucket folder. For detailed permissions of Object Storage, please refer to Manage permission.

Request Syntax

Request Syntax
curl --location --request DELETE 'https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/{directory}/?dir-delete' \
--header 'X-Auth-Token: {X-Auth-Token}'

API method

Method	Request URL
DELETE	`https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}/{directory}/?dir-delete`

Path	Type	Required or not	Description
account	String	Required	Project ID - Able to get this information when issuing a token - Used as the account value in Swift API
bucket_name	String	Required	Bucket name
directory	String	Select	The name of the directory whose child objects you want to delete

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Authentication token

Response Syntax

Status Code

HTTP Status	Response	Description
`200`	OK	Success
`400`	Bad Request	Bad request (bad name convention or non-existent)
`401`	Unauthorized	Authentication failed
`403`	Forbidden	No permission

Query bucket meta

If you have storage.buckets.get permission, you can view bucket meta information. For detailed permissions of Object Storage, please refer to Manage permission.

Bucket meta inquiry can be done in two ways: the GET and HEAD methods below.

GET method
HEAD method

Request Syntax

Request Syntax
curl --location --request GET 'https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}'

API method

Method	Request URL
GET	`https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}`

Path	Type	Required or not	Description
bucket_name	String	Required	Bucket name

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Authentication token

Response Syntax

Response Header

Request	Type	Required or not	Description
X-Container-Meta-*	String	Required	Custom Meta Information

Response Elements

Response	Type	Description
project	string	Project ID
name	string	Bucket name
type	string	Bucket type - `STANDARD`
bytes	int	Total capacity of objects included in the bucket - However, it is updated every 30 minutes and may differ from the current usage
objectCount	int	Total number of objects included in the bucket - However, it is updated every 30 minutes and may differ from the current number
createdAt	time	Bucket creation date and time
use_encryption	boolean	Whether the bucket is encrypted
lastModified	time	bucket last modified date
storageClass	string	Storage class type - `STANDARD`
acl ▼	List	Access management policy
public	string	Whether to allow public access - `read-only`,`deny`
public_read_allow_ip_list	string	List of IPs allowed for public access - If an IP list is set, access without a token is only possible for that IP

Status Code

HTTP Status	Response	Description
`200`	Success	Success
`401`	Unauthorized	Authentication failed
`403`	Forbidden	No permission
`404`	Not found	Bucket not found

Request Syntax

Request Syntax
curl --location --request HEAD 'https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'X-Object-Meta-Company: kakao enterprise'

API method

Method	Request URL
HEAD	`https://objectstorage.kr-central-2.kakaocloud.com/v1/{account}/{bucket_name}`

Path	Type	Required or not	Description
account	String	Required	Project ID - Able to get this information when issuing a token - Used as account value in Swift API
bucket_name	String	Required	Bucket name

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Authentication token

Response Syntax

Response Header

Request	Type	Required or not	Description
X-Container-Meta-*	String	Required	Custom meta information

Response Elements

Response	Type	Description
Date	time	Bucket creation date request Request time
X-Container-Bytes-Used	int	Total capacity of objects included in the bucket - However, it is updated every 30 minutes and may differ from the current usage
X-Container-Bytes-Used-Actual	int	backend storage block allocation size
X-Container-Object-Count	int	Total number of objects included in the bucket - However, it is updated every 30 minutes and may differ from the current number
X-Storage-Class	string	Storage class type - `STANDARD`
X-Storage-Policy	string	Policies applied to the repository - `default-placement`

Status Code

HTTP Status	Response	Description
`200`	Success	Success
`401`	Unauthorized	Authentication failed
`403`	Forbidden	No permission
`404`	Not found	Bucket not found

Change bucket meta

If you have storage.buckets.update permission, you can change the meta information of a bucket for which you have bucket meta access. For detailed permissions of Object Storage, please refer to Manage permission.

Request Syntax

Request Syntax
curl --location --request POST 'https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}' \
--header 'X-Auth-Token: {x-auth-token}' \
--header 'X-Object-Meta-Company: kakao enterprise'

API method

Method	Request URL
POST	`https://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}`

Request Element

Path	Type	Required or not	Description
region_name	String	Required	Region name
account	String	Required	Project ID - Able to get this information when issuing a token - Used as the account value in Swift API
bucket_name	String	Required	Bucket name

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Authentication token
X-Object-Meta-`{name}`	String	Required	For bucket meta information, enter the metadata name to specify in `{name}`

Response Syntax

Status Code

HTTP Status	Response	Description
`200`	Success	Success
`401`	Unauthorized	No permission

Bucket CORS policy

Configure bucket CORS policy settings

Users with the storage.buckets.setIamPolicy permission can set CORS policies for individual buckets. For detailed permissions of Object Storage, please refer to Manage permission. When new CORS settings are applied to a bucket, the entire list is updated.

When entering “cors” =[] or an empty body, the previously set cors details are deleted and the default CORS policy is applied. CORS settings set this way will only work with the APIs below.
The APIs below can return results accordingly if CORS is set through PUT /v1_ext/bucket/:name/cors in the container.
- /v1/:account/:container
- /v1/:account/:container/*object
- /:bucket (kr-central-2 s3 api)
- /:bucket/*object (kr-central-2 s3 api)

info

If the CORS policy is not set, access from external domains other than the console is not allowed.

Request Syntax

Request Syntax
curl --request PUT --location 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/cors' \
--header 'X-Auth-Token: {x-auth-token}'     \
--header 'Content-Type: application/json'   \
--data '{
  "cors": [
    {
      "allowed_origins": [
        "https://www.example1.com"
      ],
      "allowed_methods": [
        "PUT",
        "GET"
      ],
      "allowed_headers": [
        "*"
      ],
      "expose_headers": [],
      "max_age_seconds": 10
    },
    {
      "allowed_origins": [
        "https://www.example2.com"
      ],
      "allowed_methods": [
        "PUT",
        "GET",
        "DELETE"
      ],
      "allowed_headers": [
        "*"
      ],
      "expose_headers": [
        "X-Object-Meta-User-Defined"
      ],
      "max_age_seconds": 10
    }
  ]
}'

API method

Method	Request URL
POST	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/cors`

Path	Type	Required or not	Description
region_name	String	Required	Region name
bucket_name	String	Required	Bucket name

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Authentication token
Content-Type	String	Required	Fixed with `application/json`

Request Elements

Request	Type	Required or not	Description
region_name	String	Required	Region name
cors ▼	list	Required	CORS Policies - Maximum number of CORS policies that can be set: 10
allowed_origins	List	Required	Allow access origin - Includes protocols such as `http` or `https` - Includes up to 1 `*` (wildcard) character - Maximum input length per origin: 200 - The port can be specified - If 80 or 443 is specified as the port along with the protocol, if the Origin Header entered later specifies only the protocol and does not specify the port, the cors allow header is returned. Not working
allowed_methods	List	Required	Methods to allow access - `PUT`, `POST`, `GET`, `DELETE`, etc.
allowed_headers	List	Required	Header to allow access
expose_headers	List	Required	Headers exposed to browser
max_age_seconds	Int	Select	Lifespan for caching preflight request results - If not entered, no caching

Response Syntax

Response Syntax
{
  "cors": [
    {
      "allowed_origins": [
        "https://www.example1.com"
      ],
      "allowed_headers": [
        "*"
      ],
      "allowed_methods": [
        "PUT",
        "GET"
      ],
      "expose_headers": [],
      "max_age_seconds": 10
    },
    {
      "allowed_origins": [
        "https://www.example2.com"
      ],
      "allowed_headers": [
        "*"
      ],
      "allowed_methods": [
        "PUT",
        "GET",
        "DELETE"
      ],
      "expose_headers": [
        "X-Object-Meta-User-Defined"
      ],
      "max_age_seconds": 10
    }
  ]
}

Status Code

HTTP Status	Response	Description
`200`	OK	Success
`400`	Bad Request	Bad Request (Bad Name Rule)
`401`	Unauthorized	Authentication failed
`403`	Forbidden	No permission
`404`	Not found	Bucket not found

Query bucket CORS policy

If you have storage.buckets.getIamPolicy permission, you can query CORS settings for individual buckets. For detailed permissions of Object Storage, please refer to Manage permission.

Request Syntax

Request Syntax
curl --request GET --location 'https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/cors' \
--header 'X-Auth-Token: {x-auth-token}'     \
--header 'Content-Type: application/json'

API method

Method	Request URL
GET	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/{bucket_name}/cors`

Request Element

Path	Type	Required or not	Description
region_name	String	Required	Region name
bucket_name	String	Required	Bucket name

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Authentication token
Content-Type	String	Required	Fixed with `application/json`

Response Syntax

Response Syntax
{
    "cors": [
        {
            "allowed_origins": [
                "https://www.example1.com"
            ],
            "allowed_headers": [
                "*"
            ],
            "allowed_methods": [
                "PUT",
                "GET"
            ],
            "expose_headers": [],
            "max_age_seconds": 10
        },
        {
            "allowed_origins": [
                "https://www.example2.com"
            ],
            "allowed_headers": [
                "*"
            ],
            "allowed_methods": [
                "PUT",
                "GET",
                "DELETE"
            ],
            "expose_headers": [
                "X-Object-Meta-User-Defined"
            ],
            "max_age_seconds": 10
        }
    ]
}

Response Elements

Request	Type	Required or not	Description
cors ▼	List	Required	CORS Policies - Maximum number of CORS policies that can be set: 10
allowed_origins	List	Required	Allow access origin - Contains up to 1 `*` (wildcard) character - Maximum input length per origin: 200
allowed_methods	List	Required	Method to allow access (`HTTP`)
allowed_headers	List	Required	Header to allow access
expose_headers	List	Required	Headers exposed to browser
max_age_seconds	Int	Select	Lifespan for caching preflight request results

Status Code

HTTP Status	Response	Description
`200`	OK	Success
`400`	Bad Request	Bad request (bad name convention or non-existent)
`401`	Unauthorized	Authentication failed
`403`	Forbidden	No permission

CORS preflight request

You can request CORS Preflight for your bucket.

The API at the bottom can return results accordingly if the container has CORS set through PUT /v1_ext/bucket/:name/cors.
- /v1/:account/:container
- /v1/:account/:container/*object
- /:bucket (kr-central-2 s3 api)
- /:bucket/*object (kr-central-2 s3 api)

Request Syntax

Request Syntax
curl --location --request OPTIONS 'http://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/test.txt' \
--header 'Origin: https://www.example1.com' \
--header 'Access-Control-Request-Headers: X-Auth-Token,Content-Type' \
--header 'Access-Control-Request-Method: GET'

Request Element

Path	Type	Required or not	Description
account	String	Required	Project ID - Able to get this information when issuing a token - Used as the account value in Swift API
bucket_name	String	Required	Bucket name

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Authentication token

API method

Method	Request URL
OPTIONS	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket`
OPTIONS	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/:name` - name: Bucket name
OPTIONS	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/:name/policy` - name: Bucket name
OPTIONS	`https://objectstorage.{region_name}.kakaocloud.com/v1_ext/bucket/:name/policy/:id` - name: Bucket name - id: policy ID
OPTIONS	`https://objectstorage.{region_name}.kakaocloud.com/v1/:account/:name` - account: Project ID - name: Bucket name
OPTIONS	`https://objectstorage.{region_name}.kakaocloud.com/v1/:account/:name/object` - account: Project ID - name: Bucket name - object: object path
OPTIONS	`https://objectstorage.kr-central-2.kakaocloud.com/v1/:name` - name: Bucket name
OPTIONS	`https://objectstorage.{region_name}.kakaocloud.com/v1/:name/object` - name: Bucket name - object: object path

Request Header

Request	Type	Required or not	Description
Origin	String	Required	Origin - Server location including Protocol, Host, and Port
Access-Control-Request-Headers	List	Required	List of preliminary request headers - `X-Auth-Token`, `Content-Type`
Access-Control-Request-Method	List	Required	List of preliminary request methods - Example: `PUT`, `POST`, `GET`, `DELETE`

Response Header

Response	Type	Description
Content-Length	Int	Body length
Access-Control-Allow-Credentials	Boolean	Option to allow sharing of cookies between different domains - `true`: Allow - `false`: Do not allow
Access-Control-Allow-Headers	String	HTTP headers that can allow access to resources
Access-Control-Allow-Methods	String	HTTP method that allows access to the resource
Access-Control-Allow-Origin	String	Origins that allow access
Access-Control-Expose-Headers	String	Headers exposed to browser
Access-Control-Max-Age	Int	Time to cache the result of a preflight request

Response Syntax

Response Syntax
HTTP/1.1 200 OK
Content-Length: 0
Connection: keep-alive
Access-Control-Allow-Credentials: true
Access-Control-Allow-Headers: *
Access-Control-Allow-Methods: PUT, GET
Access-Control-Allow-Origin: https://www.example1.com
Access-Control-Expose-Headers:
Access-Control-Max-Age: 10
Vary: Origin
Strict-Transport-Security: max-age=31536000; includeSubDomains

Status Code

HTTP Status	Response	Description
`200`	OK	Success
`401`	Unauthorized	Authentication failed
`403`	Forbidden	No permission

Requests other than CORS Preflight

CORS comparison is performed based on the request, and for requests that do not meet CORS settings, Access-Control-Allow-Header, Access-Control-Allow-Methods, and Access-Control-Max-Age Header are not returned. not. To apply CORS, Origin must be set in the header.

Request Syntax

Request Syntax
curl --location --request GET 'http://objectstorage.{regoin_name}.kakaocloud.com/v1/{account}/{bucket_name}/{object}' \
--header 'x-auth-token: {x-auth-token}' \
--header 'Origin: https://www.example1.com'

API 호출 방식

Method	URL
GET	`http://objectstorage.{region_name}.kakaocloud.com/v1/{account}/{bucket_name}/{object}`

Request Element

Path	Type	Required or not	Description
region_name	String	Required	Region name
account	String	Required	Project ID - Able to get this information when issuing a token - Used as the account value in Swift API
bucket_name	String	Required	Bucket name
object	String	Required	Object name

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Authentication token

Response Syntax

Response Header Syntax
HTTP/1.1 200 OK
Content-Type: text/plain
Content-Length: 10
Access-Control-Allow-Credentials: true
Access-Control-Allow-Origin: https://www.example1.com
Access-Control-Allow-Methods: PUT, GET
Access-Control-Expose-Headers: {}
Etag: {ETag value}
Last-Modified: Thu, 07 Jul 2022 08:13:27 GMT
Vary: Origin

Response Elements

Response	Description
Content-Type	Used to indicate the media type of the resource
Content-Length	Size of the object body in bytes sent to the recipient
Access-Control-Allow-Credentials	Option to allow cookie sharing between different domains - `true`: Allow - `false`: Do not allow
Access-Control-Allow-Origin	Origin that allows access
Access-Control-Expose-Headers	Headers exposed to browser
Etag	Object's unique hash value - The ETag HTTP response header is an identifier that identifies a specific version of the resource - When the web server checks for content changes and finds none, it avoids sending a full request to the web server, enabling efficient cache usage and bandwidth savings. - Useful for preventing “mid-air collisions” when changes are made
Last-Modified	Last modified date - A response that contains the last modified date and time known to the server in the HTTP header

Status Code

HTTP Status	Response	Description
`200`	OK	Success
`401`	Unauthorized	Authentication failed
`403`	Forbidden	No permission

Bucket lifecycle

The storage.buckets.update permission is required to create and manage a bucket's LifeCycle. For detailed permissions of Object Storage, please refer to Manage permission.

Create bucket lifecycle

When creating a bucket life cycle, the previously created life cycle is overwritten. Therefore, If you need to update only part of the existing life cycle, you must receive the entire settings, modify only the necessary parts, and then request an update.

Request Syntax

Request Syntax
PUT /v1_ext/bucket/{bucket_name}/lifecycle
X-Auth-Token: {x-auth-token}
 
<?xml version="1.0"?>
<LifecycleConfiguration>
    <Rule>
        <ID>day1Rule</ID>
        <Expiration>
            <Days>1</Days>
        </Expiration>
        <Prefix>expire1/</Prefix>
        <Status>Enabled</Status>
    </Rule>
    <Rule>
        <ID>dateRule</ID>
        <Expiration>
            <Date>2023-06-10T00:00:00.000Z</Date>
        </Expiration>
        <Prefix>20230-06-08/</Prefix>
        <Status>Enabled</Status>
    </Rule>
</LifecycleConfiguration>

API method

Method	Request URL
PUT	`https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle`

Path	Type	Required or not	Description
bucket_name	String	Required	Bucket name

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Authentication token

Request Body

Request	Type	Required or not	Description
Rule ▼	List	Required	Life cycle policy
ID	String	Select	ID that identifies the rule - Unique string of up to 255 characters
Expiration ▼	Structure	Required	Settings for deletion - Date or Days fields must be entered
Date	Timestamp	Select	Date to delete object - Only `2023-06-10T00:00:00.000Z` in GMT ISO 8601 format can be entered
Days	integer	Select	Life cycle of an object - The object is deleted after the date set based on the creation date - Only positive numbers other than 0 can be entered
Filter ▼	Structure	Select	Specifies the conditions of the object to which the life cycle will be applied
Prefix	String	Required	Prefix of the object to which the rule will be applied - The following special characters must be replaced with XML entity codes `'` → `&apos`; `”` → `&quot`; `&` → `&` `<` → `<` `>` → `>` `\r` → ` ` or ` ` `\n` → ` ` or ` ` For detailed explanation, see XML-Related Object Key Constraints in AWS
Status	String	Required	Whether to apply lifecycle - Enabled: Lifecycle is set - Disabled: Lifecycle is not set

Response Syntax

Response Syntax
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 01 Feb 2023 07:23:12 GMT
Content-Length: 376
 
<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
    <Rule>
        <ID>day1Rule</ID>
        <Expiration>
            <Days>1</Days>
        </Expiration>
        <Prefix>expire1/</Prefix>
        <Status>Enabled</Status>
    </Rule>
    <Rule>
        <ID>dateRule</ID>
        <Expiration>
            <Date>2023-06-10T00:00:00.000Z</Date>
        </Expiration>
        <Prefix>20230-06-08/</Prefix>
        <Status>Enabled</Status>
    </Rule>
</LifecycleConfiguration>

Response Elements

Response	Type	Description
Rule ▼	List	Life cycle policy
ID	string	ID that identifies the rule - Unique string of up to 255 characters
Prefix	string	Prefix of the object to which the rule will be applied - The following special characters are replaced with XML entity codes `'` → ' ” → " & → & < → < > → > \r → or \n → or For a detailed explanation, see AWS's XML-related object key constraints
Status	string	Whether to apply lifecycle - `Enabled`: Lifecycle is set - `Disabled`: Lifecycle is not set
Expiration	integer	Settings for deletion

Status Code

HTTP Status	Response	Description
`200`	OK	Success
`400`	Bad Request	Configuration setting error
`401`	Unauthorized	Authentication failed
`403`	Forbidden	No permission
`404`	Not found	Bucket not found

View bucket lifecycle list

If you have storage.buckets.update permission, you can create and manage lifecycle for Object Storage, defining a set of life cycle rules to apply to groups of objects. You can manage storage space efficiently by deleting unused files through the life cycle of the bucket.

info

Expiry rule of a lifecycle runs once a day, at 00:00 (midnight). If the life cycle policy is deleted before 00:00 or 12:00 on the day the object expires, the policy will not be applied immediately.

Request Syntax

Request Syntax
curl --location --request GET 'https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle' \
--header 'X-Auth-Token: {X-Auth-Token}' 

API method

Method	Request URL
GET	`https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle`

Path	Type	Required or not	Description
bucket_name	string	Required	Bucket name

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Authentication token

Response Syntax

Response Syntax
HTTP/1.1 200 OK
Content-Type: application/xml; charset=utf-8
Date: Wed, 01 Feb 2023 07:23:12 GMT
Content-Length: 376

<?xml version="1.0" encoding="UTF-8"?>
<LifecycleConfiguration>
    <Rule>
        <ID>day1Rule</ID>
        <Expiration>
            <Days>1</Days>
        </Expiration>
        <Prefix>expire1/</Prefix>
        <Status>Enabled</Status>
    </Rule>
    <Rule>
        <ID>dateRule</ID>
        <Expiration>
            <Date>2023-06-10T00:00:00.000Z</Date>
        </Expiration>
        <Prefix>20230-06-08/</Prefix>
        <Status>Enabled</Status>
    </Rule>
</LifecycleConfiguration>

Response Elements

Response	Type	Description
Rule ▼	List	Lifecycle policy
ID	string	ID that identifies the rule - Unique string of up to 255 characters
Prefix	string	Prefix of the object to which the rule will be applied - The following special characters are replaced with XML entity codes `'` → `'` `”` → `"` `&` → `&` `<` → `<` `>` → `>` `\r` → `&#13 ;` or ` ` `\n` → ` ` or ` ` For detailed explanation, see XML-related object key constraints in AWS. Conditions document Reference
Status	string	Whether to apply life cycle - `Enabled`: Life cycle is set - `Disabled`: Life cycle is not set
Expiration	integer	Settings for deletion

Status Code

HTTP Status	Response	Description
`200`	Success	Success
`400`	Bad Request	Configuration setting error
`401`	Unauthorized	Authentication failed
`403`	Forbidden	No permission
`404`	Not Found	No bucket

Delete bucket LifeCycle

Users with LifeCycle access can delete a LifeCycle from a bucket.

Request Syntax

Request Syntax
curl --location --request DELETE 'https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle' \
--header 'X-Auth-Token: {X-Auth-Token}'

API method

Method	Request URL
DELETE	`https://objectstorage.kr-central-2.kakaocloud.com/v1_ext/bucket/{bucket_name}/lifecycle`

Path	Required or not	Type	Description
bucket_name	Required	String	Bucket name

Request Header

Request	Type	Required or not	Description
X-Auth-Token	String	Required	Authentication token

Response Syntax

Status Code

HTTP Status	Response	Description
`200`	OK	Success
`400`	Bad Request	Configuration setting error
`401`	Unauthorized	Authentication failed
`403`	Forbidden	No permission
`404`	Not found	Bucket not found

API preparations​

API endpoint​

Create bucket​

Request Syntax​

API method​

Request Header​

Request Elements​

Response Syntax​

Response Elements​

Status Code​

Manage bucket​

View bucket details​

Request Syntax​

API method​

Request Header​

Response Syntax​

Response Elements​

Status Code​

Query bucket list​

Request Syntax​

API method​

Request Element​

Request Header​

Request Query​

Response Syntax​

Response Elements​

Status Code​

Manage bucket access​

Request Syntax​

API method​

Request Header​

Request Elements​

Response Syntax​

Response Elements​

Status Code​

S3 bucket access control​

API method​

Request Header​

Request Elements​

Status Code​

Delete bucket​

Request Syntax​

API method​

Request Element​

Request Header​

Response Syntax​

Status Code​

Empty bucket​

Request Syntax​

API method​

Request Header​

Response Syntax​

Status Code​

Empty bucket folder​

Request Syntax​

API method​

Request Header​

Response Syntax​

Status Code​

Query bucket meta​

Request Syntax​

API method​

Request Header​

Response Syntax​

Response Header​

Response Elements​

Status Code​

Request Syntax​

API method​

Request Header​

Response Syntax​

Response Header​

Response Elements​

Status Code​

Change bucket meta​

Request Syntax​

API method​

Request Element​

Request Header​

Response Syntax​

API preparations

API endpoint

Create bucket

Request Syntax

API method

Request Header

Request Elements

Response Syntax

Response Elements

Status Code

Manage bucket

View bucket details

Request Syntax

API method

Request Header

Response Syntax

Response Elements

Status Code

Query bucket list

Request Syntax

API method

Request Element

Request Header

Request Query

Response Syntax

Response Elements

Status Code

Manage bucket access

Request Syntax

API method

Request Header

Request Elements

Response Syntax

Response Elements

Status Code

S3 bucket access control

API method

Request Header

Request Elements

Status Code

Delete bucket

Request Syntax

API method

Request Element

Request Header

Response Syntax

Status Code

Empty bucket

Request Syntax

API method

Request Header

Response Syntax

Status Code

Empty bucket folder

Request Syntax

API method

Request Header

Response Syntax

Status Code

Query bucket meta

Request Syntax

API method

Request Header

Response Syntax

Response Header

Response Elements

Status Code

Request Syntax

API method

Request Header

Response Syntax

Response Header

Response Elements

Status Code

Change bucket meta

Request Syntax

API method

Request Element

Request Header

Response Syntax