All Documents
Current Document

Content is empty

If you don't find the content you expect, please try another search term


PUT Bucket

Last updated:2021-09-14 16:18:03


This PUT operation will create a new bucket for the user. The user needs to be a registered user and use valid Access Key ID authentication to send the request. No anonymous request will be allowed to create a user bucket. Users will be the owners of their creation bucket, with the highest permissions.

Naming rules for bucket

We recommend that all storage space names follow DNS naming conventions.

Note: If you use the KS3 management console, the storage name must be DNS compliant in all regions.

DNS compliant storage space names enable customers to benefit from new features and operational improvements, and support virtual managed type access to storage space. There is only one unified naming method for storage space. DNS compliant storage name rules are as follows:

  • The storage space name must be at least 3 characters long and cannot exceed 63 characters.

  • The storage space name must be a series of one or more labels, which can be connected with hyphens (-). Storage space names can contain lowercase letters, numbers, hyphens (-), and cannot contain periods (.). The storage space name must start and end with a lowercase letter or number.

  • The name of the storage space must not be in IP address format (for example,

The following example is a valid storage space name:

  • my-ksbucket
  • myksbucket123
  • 123myksbucket

The following example is an invalid storage name:

  • -myksbucket The bucket name cannot start with a hyphen (-).
  • myksbucket- The bucket name cannot end with a hyphen (-).
  • my.ksbucket The bucket name cannot contain a period (.).

When users use this interface to create a space, they can grant other users or groups permission to operate on the space. The following lists two authorization methods implemented by request headers.

  • Use the x-kss-acl request header to specify a predefined 'ACL'.
  • Use x-kss-grant-read,x-kss-grant-write and x-kss-grant-full-control request headers to specify specific access rights.



PUT / HTTP/1.1
Host: {BucketName}.{endpoint}
Content-Length: {length}
Date: {date}
Authorization: {SignatureValue}

<CreateBucketConfiguration xmlns="">


Request parameters

The interface does not use request parameters.

Request header

This interface can use common request headers. For more information, please click Public request headers.

Users can specify the bucket type through the x-kss-bucket-type request header, NORMAL for non archive storage Bucket, ARCHIVE for archive storage Bucket.

Name Description Necessity
x-kss-bucket-type Used to specify bucket type.
Default value: NORMAL
Constraints: None

The user can use the following header to set a preset ACL for the bucket

Name Description Necessity
x-kss-acl Used to set predefined permissions for an object.
Type: String
Default value: private
Valid value: private public-read public-read-write
Constraints: None

Users can use the following headers to set detailed ACL for buckets

Name Description Necessity
x-kss-grant-read Grant READ permission to several users.
Type: String
Default: None
Constraints: None
x-kss-grant-write Grant WRITE permission to several users.
Type: String
Default: None
Constraints: None
x-kss-grant-full-control Grant FULL_CONTROL to several users.
Type: String
Default: None
Constraints: None

The value of the above header value is a comma separated authorization list. The format of each authorization information is type = value. The current type supports ID:

  • ID: user ID of the authorized person

For example, to grant WRITE permission to two users with ID 1234578 and 3344211: x-kss-grant-write:id="1234578",id="3344211"

Request content

Name Description Necessity
CreateBucketConfiguration Container for user space configuration information.
Type: Container
Parent node: None
LocationConstraint Specifies the region where the user space will be created.
Type: String
Default: BEIJING
Parent node: CreateBucketConfiguration


Response header

This interface can use all common response headers. For more information, please click Public response headers.

Response content

The interface does not return the corresponding content.

Special errors

The interface does not return any special errors.


Request example

PUT / HTTP/1.1
Content-Length: 0
Date: Fri, 26 Dec 2014 06:30:04 GMT
Authorization: authorization string

Response example

HTTP/1.1 200 OK
Date: Fri, 26 Dec 2014 06:30:04 GMT
Content-Length: 0
Connection: close
Server: Tengine

Interface details

  • The bucket name is globally unique. If the name of new bucket already exists, KS3 will return 409.
  • For most users, setting ACL with x-kss-acl is enough. For bucket, it is usually set to private.
On this page
Pure ModeNormal Mode

Pure Mode

Click to preview the document content in full screen