Bucket

You can use the Bucket API of Object Storage to manage bucket creation and related information and policies.

Prerequisite

• For the prerequisite tasks required to call the API, see Prepare to use APIs.

API endpoint URL

The Object Storage API endpoint URL for the kr-central-2 region is as follows.

Object Storage API endpoint URL format

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

Create bucket

Create a bucket.

Permission info

According to KakaoCloud IAM roles, the Project admin or Project member role is required to create a bucket.

Request Syntax

Create bucket request syntax

curl --request PUT --location 'https://objectstorage.{Region_Name}.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 call method

Method	Request URL
PUT	https://objectstorage.{Region_Name}.kakaocloud.com/v1_ext/bucket

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	Enter the API authentication token

| Content-Type | String | Required   | Fixed to application/json |

Request Elements

Request	Type	Required	Description
name	String	Required	Bucket name
type	String	Required	Bucket type - Standard (default): standard bucket
use_encryption	Boolean	Optional	Whether to encrypt the bucket If encryption_configuration is specified, this value is ignored - false (default): Do not encrypt - true: Encrypt (same as encryption_configuration.type = managed)
encryption_configuration ▼	Structure	Optional	Bucket encryption settings
type	String	Required	Encryption method - managed (default): automatic encryption provided by the server - true (planned): encryption integrated with a key management service using KMS

Response Syntax

Create bucket 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 - The Account value in the Swift API. You can check it when issuing a token (the project ID used/checked during the token issuance process)
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 the bucket
createdAt	String	Creation date - Format: RFC3339 - Example: 2020-07-01T00:00:00Z
use_encryption	Boolean	Whether to encrypt the bucket - false (default): Do not encrypt - true: Encrypt
encryption_type	String	Bucket encryption type
lastModified	String	Last modified date - Format: RFC3339 - Example: 2020-07-01T00:00:00Z
storageClass	String	Storage class type - STANDARD (default): bucket of the standard class
storagePolicy	String	Zone of the storage class - default-placement (default)
acl ▼	-	Access permission for the bucket - If null is entered, the 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	Invalid input settings
401	Unauthorized	No permission
409	Conflicts	Creation failed - The same Bucket_Name already exists

Manage bucket

View bucket details

If you have the storage.buckets.get permission, you can view detailed information about a specific bucket. For detailed permissions of Object Storage, see Roles and permissions.

Request Syntax

View bucket details 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 call method

Method	Request URL
GET	https://objectstorage.{Region_Name}.kakaocloud.com/v1_ext/{Bucket_Name}

Path	Type	Required	Description
Region_Name	String	Required	Region name - kr-central-2
Bucket_Name	String	Required	Bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	Enter the API authentication token

Response Syntax

View bucket details 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 - Can be checked when issuing a token (the project ID used/checked during the token issuance process) - Used in the 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 the bucket
createdAt	String	Creation date - Format: RFC3339 - Example: 2020-07-01T00:00:00Z
use_encryption	Boolean	Whether to encrypt the bucket - false (default): Do not encrypt - true: Encrypt
encryption_type	String	Bucket encryption type
lastModified	String	Last modified date - Format: RFC3339 - Example: 2020-07-01T00:00:00Z
storageClass	String	Storage class type (provided only in kr-central-2) - standard (default): bucket of the standard class
storagePolicy	String	Zone of the storage class
acl ▼	-	Access permission for the bucket - If null is entered, the existing ACL settings are deleted
public	String	Read-only - Only read-only can be entered
public_read_allow_ip_list	List	IPs allowed for public access

Status code

HTTP Status	Response	Description
200	OK	Success
400	Bad Request	Invalid input settings
401	Unauthorized	Authentication failed
403	Forbidden	No permission

View bucket list

You can view the bucket list.

Permission info

According to KakaoCloud IAM roles, the Project admin or Project member role is required to view buckets.

Request Syntax

View bucket list 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 call method

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

Request Element

Path	Type	Required	Description
Region_Name	String	Required	Region name - kr-central-2

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	API authentication token

Request Query

Request	Type	Required	Description
offset	Query	Optional	Retrieve n items from the offset in the bucket list - The offset starts from 0 - Default: 0
limit	Query	Optional	Limit the number of items - Default: 20 (up to 100 can be viewed)
prefix	Query	Optional	Search bucket names by prefix
include	Query	Optional	Search bucket names by included string - Cannot be used together with Prefix
type	Query	Optional	Type search condition - STANDARD (kr-central-2)
by	Query	Optional	Sort field - Bucket_Name: bucket name - bucket_type: bucket type - created_at: last modified date of the bucket - bytes_used: usage of the bucket
direct	Query	Optional	Sort order - asc: ascending (default) - desc: descending

Response Syntax

View bucket list response syntax

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

Response Elements

Response	Type	Description
totalCount	Int	Total number of buckets
offset	Int	Retrieve n items from the offset in the bucket list - From the i-th to the i+n-th item
count	Int	Number of returned buckets
items	List	Detailed information of buckets

Status code

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

Manage bucket access

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

Request Syntax

IP list-based access control request syntax

curl --request POST --location 'https://objectstorage.{Region_Name}.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 call method

Method	Request URL
POST	https://objectstorage.{Region_Name}.kakaocloud.com/v1_ext/bucket/{Bucket_Name}

Path	Type	Required	Description
Bucket_Name	String	Required	Bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	API authentication token
Content-Type	String	Required	Fixed to application/json

Request Elements

Request	Type	Required	Description
Bucket_Name	String	Required	Bucket name
acl ▼	Structure	Required	Access permission for the bucket - If null is entered, the existing ACL settings are deleted
public	String	Optional	Whether to allow public access - read-only: allow - deny: do not allow (same as acl = null)
public_read_allow_ip_list	List	Optional	List of IPs allowed to access

Response Syntax

Manage bucket access 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 checked when issuing a token (the project ID used/checked during the token issuance process). Scheduled for deletion
project	String	Project ID - Can be checked when issuing a token (the project ID used/checked during the token issuance process)
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 the 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 the bucket - false (default): Do not encrypt - true: Encrypt
encryption_type	String	Bucket encryption type
lastModified	String	Last modified date - Format: https://www.rfc-editor.org/rfc/rfc3339 - Example: 2020-07-01T00:00:00Z
storageClass	String	Storage class type - STANDARD (default): bucket of the standard class
storagePolicy	String	Zone of the storage class - default-placement (default)
acl ▼	-	Access permission for the bucket - If null is entered, the 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 permission to modify
404	Not found	Cannot find the bucket

Delete bucket

You can delete buckets owned by the user. To delete a bucket, the storage.buckets.delete permission is required.

• If objects exist in the bucket, the bucket cannot be deleted.

Request Syntax

Delete bucket 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 call method

Method	Request URL
DELETE	https://objectstorage.{Region_Name}.kakaocloud.com/v1_ext/bucket/{Bucket_Name}

Request Element

Path	Type	Required	Description
Region_Name	String	Required	Region name - kr-central-2
Bucket_Name	String	Required	Bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	API authentication token

Response Syntax

Status code

HTTP Status	Response	Description
204	No Content	Deleted successfully
401	Unauthorized	Authentication failed
404	Not found	Cannot find the bucket
409	Conflict	The bucket is not empty

Delete multiple buckets and objects

A user with delete permission can delete buckets and objects in the project in bulk.
The system attempts to delete the input list sequentially and returns each deletion result in a single response body.

• Planned for future support.

Empty bucket

If you have the storage.objects.delete permission, you can delete all objects under the bucket by emptying the bucket. For detailed permissions of Object Storage, see Roles and permissions.

Request Syntax

Empty bucket request syntax

curl --location --request DELETE 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{account}/{Bucket_Name}/?dir-delete' \
--header 'X-Auth-Token: {X-Auth-Token}'

API call method

Method	Request URL
DELETE	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{account}/{Bucket_Name}/?dir-delete

Path	Type	Required	Description
account	String	Required	Project ID - Can be checked when issuing a token (the project ID used/checked during the token issuance process) - Used as the Account value in the Swift API
directory	String	Optional	Name of the directory whose child objects you want to delete

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	API authentication token

Response Syntax

Status code

HTTP Status	Response	Description
200	OK	Success
400	Bad Request	Invalid request (invalid naming rule or does not exist)
401	Unauthorized	Authentication failed
403	Forbidden	No permission

Empty bucket folder

If you have the storage.objects.delete permission, you can delete all objects under the specified path by emptying the bucket folder. For detailed permissions of Object Storage, see Roles and permissions.

Request Syntax

Empty bucket folder request syntax

curl --location --request DELETE 'https://objectstorage.{Region_Name}.kakaocloud.com/v1/{account}/{Bucket_Name}/{directory}/?dir-delete' \
--header 'X-Auth-Token: {X-Auth-Token}'

API call method

Method	Request URL
DELETE	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{account}/{Bucket_Name}/{directory}/?dir-delete

Path	Type	Required	Description
account	String	Required	Project ID - Can be checked when issuing a token (the project ID used/checked during the token issuance process) - Used as the Account value in the Swift API
Bucket_Name	String	Required	Bucket name
directory	String	Optional	Name of the directory whose child objects you want to delete

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	API authentication token

Response Syntax

Status code

HTTP Status	Response	Description
200	OK	Success
400	Bad Request	Invalid request (invalid naming rule or does not exist)
401	Unauthorized	Authentication failed
403	Forbidden	No permission

View bucket metadata

If you have the storage.buckets.get permission, you can view bucket metadata. For detailed permissions of Object Storage, see Roles and permissions.

You can view bucket metadata in two ways using the GET and HEAD methods below.

GET method

Request Syntax

View bucket metadata (GET) 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 call method

Method	Request URL
GET	https://objectstorage.{Region_Name}.kakaocloud.com/v1_ext/bucket/{Bucket_Name}

Path	Type	Required	Description
Bucket_Name	String	Required	Bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	API authentication token

Response Syntax

Response Header

Request	Type	Required	Description
X-Container-Meta-*	String	Required	User-defined metadata

Response Elements

Response	Type	Description
project	string	Project ID
name	string	Bucket name
type	string	Bucket type - STANDARD
bytes	int	Total size of objects in the bucket - However, it is updated every 30 minutes and may differ from the current usage
objectCount	int	Total number of objects in the bucket - However, it is updated every 30 minutes and may differ from the current count
createdAt	time	Bucket creation date and time
use_encryption	boolean	Whether the bucket is encrypted
lastModified	time	Last modified date and time of the bucket
storageClass	string	Storage class type - STANDARD
acl ▼	List	Access control 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 allowed only from those IPs

Status code

HTTP Status	Response	Description
200	Success	Success
401	Unauthorized	Authentication failed
403	Forbidden	No permission
404	Not found	Cannot find the bucket

HEAD method

Request Syntax

View bucket metadata (HEAD) request syntax

curl --location --request HEAD '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 call method

Method	Request URL
HEAD	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{account}/{Bucket_Name}

Path	Type	Required	Description
account	String	Required	Project ID - Can be checked when issuing a token (the project ID used/checked during the token issuance process) - Used as the Account value in the Swift API
Bucket_Name	String	Required	Bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	API authentication token

Response Syntax

Response Header

Request	Type	Required	Description
X-Container-Meta-*	String	Required	User-defined metadata

Response Elements

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

Status code

HTTP Status	Response	Description
200	Success	Success
401	Unauthorized	Authentication failed
403	Forbidden	No permission
404	Not found	Cannot find the bucket

Modify bucket metadata

If you have the storage.buckets.update permission, you can modify metadata of a bucket for which you have metadata access permission. For detailed permissions of Object Storage, see Roles and permissions.

Request Syntax

Modify bucket metadata 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 call method

Method	Request URL
POST	https://objectstorage.{Region_Name}.kakaocloud.com/v1/{account}/{Bucket_Name}

Request Element

Path	Type	Required	Description
Region_Name	String	Required	Region name - kr-central-2
account	String	Required	Project ID - Can be checked when issuing a token (the project ID used/checked during the token issuance process) - Used as the Account value in the Swift API
Bucket_Name	String	Required	Bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	API authentication token
X-Object-Meta-{name}	String	Required	Bucket metadata. Enter the user-defined metadata name in {name}

Response Syntax

Status code

HTTP Status	Response	Description
200	Success	Success
401	Unauthorized	No permission

Bucket CORS policy

Configure bucket CORS policy

A user with the storage.buckets.setIamPolicy permission can configure a CORS policy for an individual bucket. For detailed permissions of Object Storage, see Roles and permissions. When a new CORS configuration is applied to a bucket, the entire list is updated.

• If "cors" = [] or an empty body is entered, the existing CORS settings are deleted and the default CORS policy is applied. A CORS setting configured in this way works only with the APIs below.

• The APIs below can return results according to the CORS settings if the container has CORS configured 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)

note

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

Request Syntax

Configure CORS policy 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 call method

Method	Request URL
POST	https://objectstorage.{Region_Name}.kakaocloud.com/v1_ext/bucket/{Bucket_Name}/cors

Path	Type	Required	Description
Region_Name	String	Required	Region name - kr-central-2
Bucket_Name	String	Required	Bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	API authentication token
Content-Type	String	Required	Fixed to application/json

Request Elements

Request	Type	Required	Description
Region_Name	String	Required	Region name - kr-central-2
cors ▼	list	Required	CORS policy - Maximum number of CORS policies that can be configured: 10
allowed_origins	List	Required	Allowed origins for access - Must include a protocol such as http or https - Can include up to one * (wildcard) character - Maximum length per origin: 200 - A port can be specified - If port 80 or 443 is specified together with the protocol, and a later Origin Header specifies only the protocol without the port, the CORS allow header is not returned
allowed_methods	List	Required	Methods allowed for access - PUT, POST, GET, DELETE, and so on
allowed_headers	List	Optional	Headers allowed for access
expose_headers	List	Optional	Headers exposed to the browser
max_age_seconds	Int	Optional	Lifetime for caching the preflight request result - If omitted, the result is not cached

Response Syntax

Configure CORS policy 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	Invalid request (invalid naming rule)
401	Unauthorized	Authentication failed
403	Forbidden	No permission
404	Not found	Cannot find the bucket

View bucket CORS policy

If you have the storage.buckets.getIamPolicy permission, you can view the CORS settings for an individual bucket. For detailed permissions of Object Storage, see Roles and permissions.

Request Syntax

View CORS policy 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 call method

Method	Request URL
GET	https://objectstorage.{Region_Name}.kakaocloud.com/v1_ext/bucket/{Bucket_Name}/cors

Request Element

Path	Type	Required	Description
Region_Name	String	Required	Region name - kr-central-2
Bucket_Name	String	Required	Bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	API authentication token
Content-Type	String	Required	Fixed to application/json

Response Syntax

View CORS policy 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	Description
cors ▼	List	Required	CORS policy - Maximum number of CORS policies that can be configured: 10
allowed_origins	List	Required	Allowed origins for access - Can include up to one * (wildcard) character - Maximum length per origin: 200
allowed_methods	List	Required	Methods allowed for access (HTTP)
allowed_headers	List	Required	Headers allowed for access
expose_headers	List	Required	Headers exposed to the browser
max_age_seconds	Int	Optional	Lifetime for caching the preflight request result

Status code

HTTP Status	Response	Description
200	OK	Success
400	Bad Request	Invalid request (invalid naming rule or does not exist)
401	Unauthorized	Authentication failed
403	Forbidden	No permission

Request CORS preflight

You can request CORS preflight for a bucket.

• The APIs below can return results according to the CORS settings if the bucket has CORS configured 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 CORS preflight 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	Description
account	String	Required	Project ID - Can be checked when issuing a token (the project ID used/checked during the token issuance process) - Used as the Account value in the Swift API
Bucket_Name	String	Required	Bucket name

Request Header

Request	Type	Required	Description
Origin	String	Required	Origin - The server location combining protocol, host, and port
Access-Control-Request-Headers	List	Required	List of headers for the preflight request - X-Auth-Token, Content-Type
Access-Control-Request-Method	List	Required	List of methods for the preflight request - Example: PUT, POST, GET, DELETE

Response Header

Response	Type	Description
Content-Length	Int	Body length
Access-Control-Allow-Credentials	Boolean	Option that allows cookie sharing across different domains - true: allow - false: do not allow
Access-Control-Allow-Headers	String	HTTP headers allowed to access the resource
Access-Control-Allow-Methods	String	HTTP methods allowed to access the resource
Access-Control-Allow-Origin	String	Origin allowed to access
Access-Control-Expose-Headers	String	Headers exposed to the browser
Access-Control-Max-Age	Int	Time for which the preflight request result can be cached

Status code

For a CORS preflight (OPTIONS) request, the server returns a 204 No Content status code, and whether CORS is allowed is determined based on the response headers (Access-Control-Allow-*).

Bucket Lifecycle

To create and manage the lifecycle of a bucket, the storage.buckets.update permission is required. For detailed permissions of Object Storage, see Roles and permissions.

Create bucket lifecycle

When you create a bucket lifecycle, the previously created lifecycle is overwritten. Therefore, if only part of the existing lifecycle needs to be updated, you must retrieve the full configuration, modify only the required part, and then send the update request.

Request Syntax

Create bucket lifecycle 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 call method

Method	Request URL
PUT	https://objectstorage.{Region_Name}.kakaocloud.com/v1_ext/bucket/{Bucket_Name}/lifecycle

Path	Type	Required	Description
Bucket_Name	String	Required	Bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	API authentication token

Request Body

Request	Type	Required	Description
Rule ▼	List	Required	Lifecycle policy
ID	String	Optional	ID that identifies the rule - Unique string of up to 255 characters
Expiration ▼	Structure	Required	Settings for deletion - You must enter either the Date or Days field
Date	Timestamp	Optional	Date when the object is deleted - Only the GMT ISO 8601 format 2023-06-10T00:00:00.000Z can be entered
Days	integer	Optional	Lifecycle of the object - The object is deleted after the configured number of days based on the creation date - Only positive integers other than 0 can be entered
Filter ▼	Structure	Optional	Specifies the conditions of objects to which the lifecycle applies
Prefix	String	Required	Prefix of the object to which the rule applies - The following special characters must be replaced with XML entity codes ' → &apos; ” → &quot; & → &amp; < → &lt; > → &gt; \r → &#13; or &#x0D; \n → &#10; or &#x0A; For details, see AWS XML-related object key constraints
Status	String	Required	Whether to apply the lifecycle - Enabled: configure the lifecycle - Disabled: do not configure the lifecycle

Response Syntax

Create bucket lifecycle 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 applies - The following special characters are replaced with XML entity codes ' → ' ” → " & → & < → < > → > \r → or \n → or For details, see AWS XML-related object key constraints
Status	string	Whether to apply the lifecycle - Enabled: configure the lifecycle - Disabled: do not configure the lifecycle
Expiration	integer	Settings for deletion

Status code

HTTP Status	Response	Description
200	OK	Success
400	Bad Request	Invalid configuration setting
401	Unauthorized	Authentication failed
403	Forbidden	No permission
404	Not found	Cannot find the bucket

View bucket lifecycle list

If you have the storage.buckets.update permission, you can create and manage the lifecycle of Object Storage to define a set of lifecycle rules to apply to object groups. Through the bucket lifecycle, you can efficiently manage storage space by deleting unused files.

note

The expiry rule of the lifecycle runs once a day, at 00:00 (midnight). If you delete the lifecycle policy before 00:00 or 12:00 on the day the object expires, that policy is not applied immediately.

Request Syntax

View bucket lifecycle list request syntax

curl --location --request GET 'https://objectstorage.{Region_Name}.kakaocloud.com/v1_ext/bucket/{Bucket_Name}/lifecycle' \
--header 'X-Auth-Token: {X-Auth-Token}' 

API call method

Method	Request URL
GET	https://objectstorage.{Region_Name}.kakaocloud.com/v1_ext/bucket/{Bucket_Name}/lifecycle

Path	Type	Required	Description
Bucket_Name	string	Required	Bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	API authentication token

Response Syntax

View bucket lifecycle list 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 applies - The following special characters are replaced with XML entity codes ' → &apos; ” → &quot; & → &amp; < → &lt; > → &gt; \r → &#13; or &#x0D; \n → &#10; or &#x0A; For details, see AWS XML-related object key constraints
Status	string	Whether to apply the lifecycle - Enabled : configure the lifecycle - Disabled : do not configure the lifecycle
Expiration	integer	Settings for deletion

Status code

HTTP Status	Response	Description
200	Success	Success
400	Bad Request	Invalid configuration setting
401	Unauthorized	Authentication failed
403	Forbidden	No permission
404	Not Found	Bucket does not exist

Delete bucket lifecycle

A user with lifecycle access permission can delete the lifecycle of a bucket.

Request Syntax

Delete bucket lifecycle request syntax

curl --location --request DELETE 'https://objectstorage.{Region_Name}.kakaocloud.com/v1_ext/bucket/{Bucket_Name}/lifecycle' \
--header 'X-Auth-Token: {X-Auth-Token}'

API call method

Method	Request URL
DELETE	https://objectstorage.{Region_Name}.kakaocloud.com/v1_ext/bucket/{Bucket_Name}/lifecycle

Path	Required	Type	Description
Bucket_Name	Required	String	Bucket name

Request Header

Request	Type	Required	Description
X-Auth-Token	String	Required	API authentication token

Response Syntax

Status code

HTTP Status	Response	Description
200	OK	Success
400	Bad Request	Invalid configuration setting
401	Unauthorized	Authentication failed
403	Forbidden	No permission
404	Not found	Cannot find the bucket