IAM permissions for gcloud storage commands
The following table lists theIdentity and Access Management (IAM) permissionsrequired to rungcloud storage commands. IAM permissionsare bundled together to makeroles. Yougrant roles to principals.
See the sections below the table for notes on using wildcards, the--recursiveflag, and the--billing-project flag.
| Command | Flag | Required IAM Permissions |
|---|---|---|
batch-operations jobs create | storagebatchoperations.jobs.create | |
batch-operations jobs cancel | storagebatchoperations.jobs.cancel | |
batch-operations jobs delete | storagebatchoperations.jobs.delete | |
batch-operations jobs get | storagebatchoperations.jobs.get | |
batch-operations jobs list | storagebatchoperations.jobs.list | |
buckets add-iam-policy-binding | storage.buckets.getstorage.buckets.getIamPolicystorage.buckets.setIamPolicystorage.buckets.update | |
buckets anywhere-caches create | storage.anywhereCaches.create | |
buckets anywhere-caches describe | storage.anywhereCaches.get | |
buckets anywhere-caches list | storage.anywhereCaches.list | |
buckets anywhere-caches update | storage.anywhereCaches.update | |
buckets anywhere-caches pause | storage.anywhereCaches.pause | |
buckets anywhere-caches resume | storage.anywhereCaches.resume | |
buckets anywhere-caches disable | storage.anywhereCaches.disable | |
buckets create | storage.buckets.createstorage.buckets.setIpFilter15 | |
buckets delete | storage.buckets.delete | |
buckets describe | storage.buckets.getstorage.buckets.getIamPolicy1storage.buckets.getIpFilter16 | |
buckets get-iam-policy | storage.buckets.getstorage.buckets.getIamPolicy | |
buckets list | storage.buckets.liststorage.buckets.getIamPolicy1 | |
buckets notifications create | storage.buckets.getstorage.buckets.updatepubsub.topics.get (for the project containing the Pub/Sub topic)pubsub.topics.create3 (for the project containing the Pub/Sub topic)pubsub.topics.getIamPolicy (for Pub/Sub topic receiving notifications)pubsub.topics.setIamPolicy3 (for Pub/Sub topic receiving notifications) | |
buckets notifications create | --skip-topic-setup | storage.buckets.getstorage.buckets.update |
buckets notifications delete | storage.buckets.getstorage.buckets.update | |
buckets notifications describe | storage.buckets.get | |
buckets notifications list | storage.buckets.get | |
buckets relocate | storage.buckets.relocate | |
buckets remove-iam-policy-binding | storage.buckets.getstorage.buckets.getIamPolicystorage.buckets.setIamPolicystorage.buckets.update | |
buckets set-iam-policy | storage.buckets.setIamPolicystorage.buckets.update | |
buckets update | storage.buckets.updatestorage.buckets.setIpFilter15 | |
buckets update | --no-requester-pays | storage.buckets.updateresourcemanager.projects.createBillingAssignment2 |
buckets update | --recovery-point-objective--rpo--[no-]uniform-bucket-level-access | storage.buckets.getstorage.buckets.update |
buckets update | --clear-pap--clear-public-access-prevention--[no-]pap--[no-]public-access-prevention | storage.buckets.getstorage.buckets.updatestorage.buckets.setIamPolicy |
cat | storage.objects.getstorage.objects.list13 | |
cp | storage.objects.getstorage.objects.createstorage.objects.list4storage.objects.delete5storage.buckets.get12 | |
du | storage.objects.list | |
folders create | storage.folders.create | |
folders delete | storage.folders.delete | |
folders describe | storage.folders.get | |
folders list | storage.folders.list | |
folders rename | storage.folders.renamestorage.folders.create | |
hash | storage.objects.get | |
hmac create | storage.hmacKeys.create | |
hmac delete | storage.hmacKeys.delete | |
hmac describe | storage.hmacKeys.get | |
hmac list | storage.hmacKeys.list | |
hmac update | storage.hmacKeys.update | |
insights dataset-configs create | storageinsights.datasetConfigs.create | |
insights dataset-configs create-link | storageinsights.datasetConfigs.linkDataset | |
insights dataset-configs delete | storageinsights.datasetConfigs.delete | |
insights dataset-configs delete-link | storageinsights.datasetConfigs.unlinkDataset | |
insights dataset-configs describe | storageinsights.datasetConfigs.get | |
insights dataset-configs list | storageinsights.datasetConfigs.list | |
insights dataset-configs update | storageinsights.datasetConfigs.update | |
insights inventory-reports create | storageinsights.reportConfigs.create | |
insights inventory-reports delete | storageinsights.reportConfigs.delete | |
insights inventory-reports details list | storageinsights.reportDetails.list | |
insights inventory-reports details describe | storageinsights.reportDetails.get | |
insights inventory-reports list | storageinsights.reportConfigs.list | |
insights inventory-reports update | storageinsights.reportConfigs.getstorageinsights.reportConfigs.update | |
ls (for bucket listing) | storage.buckets.liststorage.buckets.getIamPolicy6 | |
ls (for object listing) | storage.objects.get7storage.objects.liststorage.objects.getIamPolicy8 | |
ls | --buckets | storage.buckets.getstorage.buckets.getIamPolicy6 |
storage intelligence-config enable | storage.intelligenceConfigs.update | |
storage-intelligence disable | storage.intelligenceConfigs.update | |
storage-intelligence describe | storage.intelligenceConfigs.get | |
storage-intelligence update | storage.intelligenceConfigs.update | |
mv | storage.objects.getstorage.objects.deletestorage.objects.createstorage.objects.list4storage.objects.delete5storage.buckets.get12 | |
objects compose | storage.objects.getstorage.objects.createstorage.objects.delete9 | |
objects describe | storage.objects.getstorage.objects.getIamPolicy8 | |
objects list | storage.objects.liststorage.objects.getIamPolicy8 | |
objects update | storage.objects.getstorage.objects.liststorage.objects.update | |
objects update | --storage-class--encryption-key--clear-encryption-key | storage.objects.getstorage.objects.liststorage.objects.createstorage.objects.delete |
objects update | --retention-mode--retain-until--clear-retention | storage.objects.getstorage.objects.liststorage.objects.updatestorage.objects.setRetentionstorage.objects.overrideUnlockedRetention11 |
operations cancel | storage.bucketOperations.cancel | |
operations describe | storage.bucketOperations.get | |
operations list | storage.bucketOperations.list | |
restore | storage.objects.createstorage.objects.delete9storage.objects.restore | |
restore | --async | storage.objects.createstorage.objects.delete14storage.objects.restorestorage.buckets.restore |
rm | storage.buckets.deletestorage.objects.deletestorage.objects.list | |
rsync | storage.objects.liststorage.objects.getstorage.objects.liststorage.objects.getstorage.objects.createstorage.objects.delete10storage.buckets.get12 | |
rsync | --dry-run | storage.objects.list (for the source and destination buckets) |
service-agent | resourceManager.projects.get | |
sign-url | None; however, the service account whose key is used as part of this command must have permission to perform the request being encoded into the signed URL. |
1This permission is only required if you want IAMpolicies included in the details.
2This permission is only required if you don't include a billingproject in your request. See Requester PaysUse and access requirementsfor more information.
3These permissions are not required if the topic already exists andthe relevant service account has access to it.
4This permission is only required when the destination in thecommand contains an object path.
5This permission is only required if you useparallel composite uploads or if you don't use the--no-clobber flag butinsert an object that has the same name as an object that already exists in thebucket.
6This permission is only required if you want IAMpolicies included in the details.
7This permission is only required if you use the--fetch-encrypted-object-hashes flag.
8This permission is only required if you want IAMpolicies included in the details, and it does not apply to buckets withuniform bucket-level access enabled.
9This permission is only required if the operation creates an objectwith the same name as an object that already exists in the bucket.
10This permission is only required if you use the--delete-unmatched-destination-objects flag or if you insert an object thathas the same name as, butdifferent data than, an object that alreadyexists in the bucket.
11This permission is only required if the request also requires youto use the--override-unlocked-retention flag.
12This permission is required to performparallel composite uploads if the gcloud CLI propertystorage/parallel_composite_upload_compatibility_check is set toTrue.
13This permission is only required if you want to use regularexpressions to retrieve objects.
14This permission is only required if the request includes the--allow-overwrite flag and the operation creates an object with the same nameas an object that already exists in the bucket.
15This permission is only required if the request includes the flag--ip-filter-file to create, update or delete the IP filtering ruleson a bucket.
16This permission is only required if you want to get the bucket's IP filter configuration as part of the response.
Note: The permissions listed in the previous table allow you to use thecommands. Some commands set bucket configurations that won't work withoutadditional permissions. For example,buckets notification create requires onlystorage.buckets.get andstorage.buckets.update to use, but you must haveadditional permissions for the feature to work properly.The--billing-project top-level flag
If you use the--billing-project global flag to specify a project thatshould be billed for your request, you must haveserviceusage.services.usepermission for the project you specify. The--billing-project flag is used,for example, when accessing a bucket withRequester Pays enabled.
Wildcards and recursive flags
If you useURI wildcards to select multiple objects in a command, youmust havestorage.objects.list permission for the bucket containing theobjects. Similarly, if you use URI wildcards to select multiple bucketsin a command, you must havestorage.buckets.list permission for theproject(s) containing the buckets.
If you use the--recursive flag, you must havestorage.objects.listpermission for the relevant bucket, in addition to the permissions required forthe specific command you are using.
What's next
- Grant IAM roles at the project and bucket level.
- ReviewIAM roles that contain Cloud Storage permissions.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2026-02-19 UTC.