Set a Cross-Origin Resource Sharing (CORS) Rule on a Specified Bucket
Updated at：2025-11-03
API description
This API is used to set a Cross-Origin Resource Sharing (CORS) rule for a specific bucket. The new rule will replace any existing rules.
Permission description Only the bucket owner or users granted with FULL_CONTROL permission can set bucket CORS. When the permission is not granted, the error 403 Forbidden will be returned with the error code AccessDenied.
Notes
- Before using this API to set CORS rules, the bucket's CORS permission is configured to disallow cross-origin operations.
- Each bucket permits only a single rule file. Therefore, uploading a new rule file will overwrite any existing rules.
- The size limit for a CORS rule file is 20KB. Requests exceeding this size will result in a 400 Bad Request error with the EntityTooLarge code.
Request URI
PUT /v1/{bucketName}/?cors
| Parameter name | Parameter type | Required or not | Description | Example value | Parameter location |
|---|---|---|---|---|---|
| bucketName | String | Yes | Bucket name | "bucketName_example" | Path |
Parameters of request body
Description of the data structure of request body fields
| Parameter name | Parameter type | Required or not | Description | Example value |
|---|---|---|---|---|
| corsConfiguration | List |
Yes | Defines container rules for bucket CORS. Each bucket can have up to 100 rules, executed in order from top to bottom if multiple configurations exist. |
Description of CorsConfiguration field data structure
| Parameter name | Parameter type | Required or not | Description | Example value |
|---|---|---|---|---|
| allowedOrigins | List |
Yes | A container that stores the allowed origins for cross-origin requests. | |
| allowedMethods | List |
Yes | A container that stores the allowed methods for cross-origin requests. | |
| allowedHeaders | List |
Yes | A container that specifies allowed headers. It determines whether the headers listed in the Access-Control-Request-Headers of an OPTIONS preflight request are permitted. | |
| allowedExposeHeaders | List |
No | A container that stores the response headers accessible to users from applications. | |
| maxAgeSeconds | Integer | No | Set the browser's cache duration (in seconds) for the responses to preflight (OPTIONS) requests. During this set time, duplicate preflight requests will not be sent. Type: Int64. | 1800 |
Response body parameters
Description of the data structure of response body fields
Request example
JSON
1PUT /v1/bucketName_example/?cors
2 <Common request headers>
3{
4 "corsConfiguration" : [ {
5 "allowedExposeHeaders" : [ "user-custom-expose-header" ],
6 "allowedOrigins" : [ "http://www.example.com" ],
7 "allowedHeaders" : [ "Authorization" ],
8 "allowedMethods" : [ "GET" ],
9 "maxAgeSeconds" : 1800
10 } ]
11}Response example
JSON
1HTTP/1.1 200 OK
2 <Common response headers>
3{ }Error code
Please refer to the general error codes