Tenant Cloud Storage Cloud Object Storage Best Practices

User Guide to COS API Authorization Policies

Last Updated At: 2025-10-21 09:10:00

Note:

Grant the minimum API operation permissions to a sub-user or collaborator based on business requirements. If you grant the permissions of all resources (resource:*) or all operations (action:*) to a sub-user or collaborator, data security risks exist due to an excessive permission scope.

Overview

If a temporary key is used to access COS, different operation permissions are required for different COS API operations. In addition, you can specify the operation permissions for one operation or a series of operations at the same time.

The COS API authorization policy is a JSON string. For example, the following policy grants the permission to upload (including simple upload, form upload, and multipart upload) objects prefixed doc and download objects prefixed doc2 in the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
    "version": "2.0",
    "statement": [{
            "action": [
                //Simple upload operation 
                "name/cos:PutObject",
                //Object upload through a form 
                "name/cos:PostObject",
                //Multipart upload: Initializing multipart upload operations 
                "name/cos:InitiateMultipartUpload",
                //Multipart upload: Listing ongoing multipart upload operations
                "name/cos:ListMultipartUploads",
                //Multipart upload: Listing uploaded parts 
                "name/cos:ListParts",
                //Multipart upload: Uploading parts 
                "name/cos:UploadPart",
                //Multipart upload: Completing all multipart upload operations 
                "name/cos:CompleteMultipartUpload",
                //Canceling multipart upload operations 
                "name/cos:AbortMultipartUpload"
            ],
            "effect": "allow",
            "resource": [
                "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc/*"
            ]
        },
        {
            "action": [
                //Downloading operation 
                "name/cos:GetObject"
            ],
            "effect": "allow",
            "resource": [
                "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc2/*"
            ]
        }
    ]
}

Authorization Policy Element Description

Name Description
version Syntax version of a policy, which is 2.0 by default.
effect The options include allow (permit) and deny (explicit refuse).
resource Authorized data to be operated, which can be any resources, resources with a specified path prefix, resources with a specified absolute path, or resources with combinations of the above conditions.
action COS API operation. You can specify an operation, the combination of a series of operations, or all operations (*) as required.
condition Constraint conditions, which can be left blank. For details, see condition description.

The following describes examples for setting authorization policies of different COS APIs.

Service API

Querying the Bucket List

To grant access to the GET Service API, the action element of the policy is name/cos:GetService, and the resource element of the policy is *.

Example

The following policy grants the permission to query the bucket list.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:GetService"
      ],
      "effect": "allow",
      "resource": [
        "*"
      ]
    }
  ]
}

Bucket API

The resource element of the bucket API policy varies depending on the scenario:

  • To operate buckets in all regions, the resource element of the policy is *.
  • To operate buckets in a specified region, for example, to operate the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000, the resource element of the policy is qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/*.
  • To operate a bucket with the specified name in the specified region, for example, to operate the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000, the resource element of the policy is qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/.
    The value of the action element in a bucket API policy varies depending on the operation. The following describes all bucket API authorization policies.

Creating a Bucket

To grant access to the PUT Bucket API, set the action element of the policy to name/cos:PutBucket.

Example

The following policy grants the permission to create a bucket with any name whose region is ap-city1 and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutBucket"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Retrieving Buckets and Their Permissions

To grant access to the HEAD Bucket API, set the action element of the policy to name/cos:HeadBucket.

Example

The following policy grants the permission to retrieve the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:HeadBucket"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Querying the Object List

To grant access to the GET Bucket API, set the action element of the policy to name/cos:GetBucket.

Example

The following policy grants the permission to query the list of objects in the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:GetBucket"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Deleting a Bucket

To grant access to the Delete Bucket API, set the action element of the policy to name/cos:DeleteBucket.

Example

The following policy grants the permission to delete the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:DeleteBucket"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Setting a Bucket ACL

To grant access to the Put Bucket ACL API, set the action element of the policy to name/cos:PutBucketACL.

Example

The following policy grants the permission to set an ACL for the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutBucketACL"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Querying the ACL of a Bucket

To grant access to the GET Bucket acl API, set the action element of the policy to name/cos:GetBucketACL.

Example

The following policy grants the permission to obtain the ACL of the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:GetBucketACL"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Setting CORS Configuration

To grant access to the PUT Bucket cors API, set the action element of the policy to name/cos:PutBucketCORS.

Example

The following policy grants the permission to set the CORS configuration for the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutBucketCORS"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Querying CORS Configuration

To grant access to the GET Bucket cors API, the action element of the policy is name/cos:GetBucketCORS.

Example

The following policy grants the permission to query the CORS configuration of the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:GetBucketCORS"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Deleting CORS Configuration

To grant access to the DELETE Bucket cors API, set the action element of the policy to name/cos:DeleteBucketCORS.

Example

The following policy grants the permission to delete the CORS configuration for the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:DeleteBucketCORS"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Setting the Bucket Lifecycle

To grant access to the PUT Bucket lifecycle API, set the action element of the policy to name/cos:PutBucketLifecycle.

Example

The following policy grants the permission to set the lifecycle for the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutBucketLifecycle"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Querying the Bucket Lifecycle Configuration

To grant access to the GET Bucket lifecycle API, set the action element of the policy to name/cos:GetBucketLifecycle.

Example

The following policy grants the permission to query the lifecycle configuration of the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:GetBucketLifecycle"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Deleting the Bucket Lifecycle Configuration

To grant access to the DELETE Bucket lifecycle API, set the action element of the policy to name/cos:DeleteBucketLifecycle.

Example

The following policy grants the permission to delete the lifecycle configuration of the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:DeleteBucketLifecycle"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Querying Multipart Upload

This API is used to query information about ongoing multipart uploads in a bucket. To grant access to this API, set the action element of the policy to name/cos:ListMultipartUploads.

Example

The following policy grants the permission to query ongoing multipart uploads in the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:ListMultipartUploads"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/"
      ]
    }
  ]
}

Object API

The resource element of an object API policy varies depending on the scenario:

  • To operate all objects, the resource element of the policy is *.
  • To operate objects in a specified bucket, for example, to operate objects in the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000, the resource element of the policy is qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/*.
  • To operate objects in a specified bucket and with the specified path prefix, for example, to operate objects in the bucket whose name is examplebucket-1250000000, region is ap-city1, app ID is 1250000000, and path prefix is doc, the resource element of the policy is qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc/*.
  • To operate objects in a specified absolute path, for example, to operate objects in the bucket whose name is examplebucket-1250000000, region is ap-city1, app ID is 1250000000, and absolute path is doc/audio.mp3, the resource element of the policy is qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc/audio.mp3.
    The value of the action element in an object API policy varies depending on the operation. The following describes all object API authorization policies.

Uploading Objects in Simple Upload Mode

To grant access to the PUT Object API, set the action element of the policy to name/cos:PutObject.

Example

The following policy grants the permission to upload objects prefixed doc in simple upload mode to the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

 {
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Multipart Upload

Multipart upload operations include Initiate Multipart Upload, List Multipart Uploads, List Parts, Upload Part, Complete Multipart Upload, and Abort Multipart Upload. To grant access to this API, set the action element of the policy to a set of "name/cos:InitiateMultipartUpload","name/cos:ListMultipartUploads","name/cos:ListParts","name/cos:UploadPart","name/cos:CompleteMultipartUpload","name/cos:AbortMultipartUpload".

Example

The following policy grants the permission to upload objects prefixed doc in multipart upload mode to the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:InitiateMultipartUpload",
        "name/cos:ListMultipartUploads",
        "name/cos:ListParts",
        "name/cos:UploadPart",
        "name/cos:CompleteMultipartUpload",
        "name/cos:AbortMultipartUpload"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Uploading Objects Through Forms

To grant access to the POST Object API, set the action element of the policy to name/cos:PostObject.

Example

The following policy grants the permission to upload objects prefixed doc in POST upload mode to the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PostObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Querying Metadata of Objects

To grant access to the HEAD Object API, set the action element of the policy to name/cos:HeadObject.

Example

The following policy grants the permission to query objects prefixed doc in the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:HeadObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Downloading an Object

To grant access to the GET Object API, set the action element of the policy to name/cos:GetObject.

Example

The following policy grants the permission to download objects prefixed doc in the bucket whose name is examplebucket-1250000000, region is ap-city1 and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:GetObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Copying Objects

To grant access to the Put Object Copy API, set the action element of the policy for the destination object to name/cos:PutObject and the action element of the policy for the source object to name/cos:GetObject.

Example

The following policy grants the permission to use multipart copy to copy objects from the path prefixed with doc to the path prefixed with doc2 in the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    },
    {
      "action": [
        "name/cos:GetObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc2/*"
      ]
    }
  ]
}

"qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc2/*" is the source object.

Copying Parts

To grant access to the Upload Part - Copy API, set the action element of the policy for the target object to a set of "name/cos:InitiateMultipartUpload","name/cos:ListMultipartUploads","name/cos:ListParts","name/cos:PutObject","name/cos:CompleteMultipartUpload","name/cos:AbortMultipartUpload", and the action element of the policy for the source object to name/cos:GetObject.

Example

The following policy grants the permission to use multipart copy to copy objects from the path prefixed with doc to the path prefixed with doc2 in the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:InitiateMultipartUpload",
        "name/cos:ListMultipartUploads",
        "name/cos:ListParts",
        "name/cos:PutObject",
        "name/cos:CompleteMultipartUpload",
        "name/cos:AbortMultipartUpload"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    },
    {
      "action": [
        "name/cos:GetObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc2/*" 
      ]
    }
  ]
}

"qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc2/*" is the source object.

Setting an ACL for Objects

To grant access to the Put Object ACL API, set the action element of the policy to name/cos:PutObjectACL.

Example

The following policy grants the permission to set an ACL for objects prefixed doc in the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PutObjectACL"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Querying an Object ACL

To grant access to the Get Object ACL API, the action element of the policy is name/cos:GetObjectACL.

Example

The following policy grants the permission to query the ACL of objects prefixed doc in the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:GetObjectACL"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Checking CORS Configuration

To grant access to the OPTIONS Object API, the action element of the policy is name/cos:OptionsObject.

Example

The following policy grants the permission to send Options requests under the bucket whose name is examplebucket-1250000000, region is ap-city1, app ID is 1250000000, and path prefix is doc.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:OptionsObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Recovering Archived Objects

To grant access to the Post Object Restore API, the action element of the policy is name/cos:PostObjectRestore.

Example

The following policy grants the permission to recover archived objects prefixed doc in the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:PostObjectRestore"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}

Deleting an Object

To grant access to the DELETE Object API, the action element of the policy is name/cos:DeleteObject.

Example

The following policy grants the permission to delete the object named audio.mp3 in the bucket whose name is examplebucket-1250000000, region is ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:DeleteObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/audio.mp3"
      ]
    }
  ]
}

Deleting Multiple Objects

To grant access to the DELETE Multiple Objects API, the action element of the policy is name/cos:DeleteObject.

Example

The following policy grants the permission to batch delete objects named audio.mp3 and video.mp4 in the bucket whose name is examplebucket-1250000000, region ap-city1, and app ID is 1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:DeleteObject"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/audio.mp3",
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/video.mp4"
      ]
    }
  ]
}

Authorization Policies in Common Scenarios

Granting Full Read and Write Permissions to All Resources

The following policy grants full read and write permissions to all resources.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "*"
      ],
      "effect": "allow",
      "resource": [
        "*"
      ]
    }
  ]
}

Granting the Read-Only Permission to All Resources

The following policy grants the read-only permission to all resources.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "name/cos:HeadObject",
        "name/cos:GetObject",
        "name/cos:ListObject",
        "name/cos:OptionsObject"
      ],
      "effect": "allow",
      "resource": [
        "*"
      ]
    }
  ]
}

Granting Read and Write Permissions to Resources with a Specified Path Prefix

The following policy grants the access permission only for files with the path prefix doc in the bucket named examplebucket-1250000000.

{
  "version": "2.0",
  "statement": [
    {
      "action": [
        "*"
      ],
      "effect": "allow",
      "resource": [
        "qcs::cos:ap-city1:uid/1250000000:examplebucket-1250000000/doc/*"
      ]
    }
  ]
}