Cloud Storage offers two systems for granting users access your buckets and objects:
IAM and Access Control Lists (ACLs). These systems act in parallel - in order for a user to
access a Cloud Storage resource, only one of the systems needs to grant that user permission.
For additional access control options, see also:
Cloud Storage Control Access to Data
ACL
Cloud Storage uses access control lists (ACLs) to manage object and bucket access.
ACLs are the mechanism you use to share files with other users and allow
other users to access your buckets and files.
ACLs are suitable for fine-grained control, but you may prefer using IAM to
control access at the project level.
This list of tuples can be used as the entity and role fields
when sending metadata for ACLs to the API.
IAM
Identity and Access Management (IAM) controls permissioning throughout Google Cloud and allows you
to grant permissions at the bucket and project levels. You should use IAM for any permissions that
apply to multiple objects in a bucket to reduce the risks of unintended exposure. To use IAM
exclusively, enable uniform bucket-level access to disallow ACLs for all Cloud Storage resources.
See also:
Additional access control options
Constants used across IAM roles:
STORAGE_OBJECT_CREATOR_ROLE = "roles/storage.objectCreator"
corresponds to role implying rights to create objects, but not delete or overwrite them.
STORAGE_OBJECT_VIEWER_ROLE = "roles/storage.objectViewer"
corresponds to role implying rights to view object properties, excluding ACLs.
STORAGE_OBJECT_ADMIN_ROLE = "roles/storage.objectAdmin"
corresponds to role implying full control of objects.
STORAGE_ADMIN_ROLE = "roles/storage.admin"
corresponds to role implying full control of objects and buckets.
STORAGE_VIEWER_ROLE = "Viewer"
corresponds to role that can list buckets.
STORAGE_EDITOR_ROLE = "Editor"
corresponds to role that can create, list, and delete buckets.
STORAGE_OWNER_ROLE = "Owners"
corresponds to role that can Can create, list, and delete buckets;
and list tag bindings; and control HMAC keys in the project.
Constants used across IAM permissions:
STORAGE_BUCKETS_CREATE = "storage.buckets.create"
corresponds to permission that can create buckets.
STORAGE_BUCKETS_DELETE = "storage.buckets.delete"
corresponds to permission that can delete buckets.
STORAGE_BUCKETS_GET = "storage.buckets.get"
corresponds to permission that can read bucket metadata, excluding ACLs.
STORAGE_BUCKETS_LIST = "storage.buckets.list"
corresponds to permission that can list buckets.
STORAGE_BUCKETS_GET_IAM_POLICY = "storage.buckets.getIamPolicy"
corresponds to permission that can read bucket ACLs.
STORAGE_BUCKETS_SET_IAM_POLICY = "storage.buckets.setIamPolicy"
corresponds to permission that can update bucket ACLs.
STORAGE_BUCKETS_UPDATE = "storage.buckets.update"
corresponds to permission that can update buckets, excluding ACLS.
STORAGE_OBJECTS_CREATE = "storage.objects.create"
corresponds to permission that can add new objects to a bucket.
STORAGE_OBJECTS_DELETE = "storage.objects.delete"
corresponds to permission that can delete objects.
STORAGE_OBJECTS_GET = "storage.objects.get"
corresponds to permission that can read object data / metadata, excluding ACLs.
STORAGE_OBJECTS_LIST = "storage.objects.list"
corresponds to permission that can list objects in a bucket.
STORAGE_OBJECTS_GET_IAM_POLICY = "storage.objects.getIamPolicy"
corresponds to permission that can read object ACLs.
STORAGE_OBJECTS_SET_IAM_POLICY = "storage.objects.setIamPolicy"
corresponds to permission that can update object ACLs.
STORAGE_OBJECTS_UPDATE = "storage.objects.update"
corresponds to permission that can update object metadata, excluding ACLs.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Hard to understand","hardToUnderstand","thumb-down"],["Incorrect information or sample code","incorrectInformationOrSampleCode","thumb-down"],["Missing the information/samples I need","missingTheInformationSamplesINeed","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2025-08-12 UTC."],[],[],null,["Version latestkeyboard_arrow_down\n\n- [3.3.0 (latest)](/python/docs/reference/storage/latest/acl_guide)\n- [3.2.0](/python/docs/reference/storage/3.2.0/acl_guide)\n- [3.1.1](/python/docs/reference/storage/3.1.1/acl_guide)\n- [3.0.0](/python/docs/reference/storage/3.0.0/acl_guide)\n- [2.19.0](/python/docs/reference/storage/2.19.0/acl_guide)\n- [2.17.0](/python/docs/reference/storage/2.17.0/acl_guide)\n- [2.16.0](/python/docs/reference/storage/2.16.0/acl_guide)\n- [2.15.0](/python/docs/reference/storage/2.15.0/acl_guide)\n- [2.14.0](/python/docs/reference/storage/2.14.0/acl_guide)\n- [2.13.0](/python/docs/reference/storage/2.13.0/acl_guide)\n- [2.12.0](/python/docs/reference/storage/2.12.0/acl_guide)\n- [2.11.0](/python/docs/reference/storage/2.11.0/acl_guide)\n- [2.10.0](/python/docs/reference/storage/2.10.0/acl_guide)\n- [2.9.0](/python/docs/reference/storage/2.9.0/acl_guide)\n- [2.8.0](/python/docs/reference/storage/2.8.0/acl_guide)\n- [2.7.0](/python/docs/reference/storage/2.7.0/acl_guide)\n- [2.6.0](/python/docs/reference/storage/2.6.0/acl_guide)\n- [2.5.0](/python/docs/reference/storage/2.5.0/acl_guide)\n- [2.4.0](/python/docs/reference/storage/2.4.0/acl_guide)\n- [2.3.0](/python/docs/reference/storage/2.3.0/acl_guide)\n- [2.2.1](/python/docs/reference/storage/2.2.1/acl_guide)\n- [2.1.0](/python/docs/reference/storage/2.1.0/acl_guide)\n- [2.0.0](/python/docs/reference/storage/2.0.0/acl_guide)\n- [1.44.0](/python/docs/reference/storage/1.44.0/acl_guide)\n- [1.43.0](/python/docs/reference/storage/1.43.0/acl_guide)\n- [1.42.3](/python/docs/reference/storage/1.42.3/acl_guide)\n- [1.41.1](/python/docs/reference/storage/1.41.1/acl_guide)\n- [1.40.0](/python/docs/reference/storage/1.40.0/acl_guide)\n- [1.39.0](/python/docs/reference/storage/1.39.0/acl_guide)\n- [1.38.0](/python/docs/reference/storage/1.38.0/acl_guide)\n- [1.37.1](/python/docs/reference/storage/1.37.1/acl_guide)\n- [1.36.2](/python/docs/reference/storage/1.36.2/acl_guide)\n- [1.35.1](/python/docs/reference/storage/1.35.1/acl_guide)\n- [1.34.0](/python/docs/reference/storage/1.34.0/acl_guide)\n- [1.33.0](/python/docs/reference/storage/1.33.0/acl_guide)\n- [1.32.0](/python/docs/reference/storage/1.32.0/acl_guide)\n- [1.31.2](/python/docs/reference/storage/1.31.2/acl_guide)\n- [1.30.0](/python/docs/reference/storage/1.30.0/acl_guide)\n- [1.29.0](/python/docs/reference/storage/1.29.0/acl_guide)\n- [1.28.1](/python/docs/reference/storage/1.28.1/acl_guide)\n- [1.27.0](/python/docs/reference/storage/1.27.0/acl_guide)\n- [1.26.0](/python/docs/reference/storage/1.26.0/acl_guide)\n- [1.25.0](/python/docs/reference/storage/1.25.0/acl_guide)\n- [1.24.1](/python/docs/reference/storage/1.24.1/acl_guide)\n- [1.23.0](/python/docs/reference/storage/1.23.0/acl_guide)\n- [1.22.0](/python/docs/reference/storage/1.22.0/acl_guide)\n- [1.21.0](/python/docs/reference/storage/1.21.0/acl_guide)\n- [1.20.0](/python/docs/reference/storage/1.20.0/acl_guide)\n- [1.19.0](/python/docs/reference/storage/1.19.0/acl_guide)\n- [1.18.0](/python/docs/reference/storage/1.18.0/acl_guide)\n- [1.17.0](/python/docs/reference/storage/1.17.0/acl_guide) \n\nManaging Access to Data\n=======================\n\nCloud Storage offers two systems for granting users access your buckets and objects:\nIAM and Access Control Lists (ACLs). These systems act in parallel - in order for a user to\naccess a Cloud Storage resource, only one of the systems needs to grant that user permission.\nFor additional access control options, see also:\n[Cloud Storage Control Access to Data](https://cloud.google.com/storage/docs/access-control)\n\nACL\n---\n\nCloud Storage uses access control lists (ACLs) to manage object and bucket access.\nACLs are the mechanism you use to share files with other users and allow\nother users to access your buckets and files.\n\nACLs are suitable for fine-grained control, but you may prefer using IAM to\ncontrol access at the project level.\n\n[`google.cloud.storage.bucket.Bucket`](/python/docs/reference/storage/latest/storage/bucket#google.cloud.storage.bucket.Bucket) has a getting method that creates\nan ACL object under the hood, and you can interact with that using\n[`google.cloud.storage.bucket.Bucket.acl()`](/python/docs/reference/storage/latest/storage/bucket#google.cloud.storage.bucket.Bucket.acl): \n\n client = storage.Client()\n bucket = client.get_bucket(bucket_name)\n acl = bucket.acl\n\nAdding and removing permissions can be done with the following methods\n(in increasing order of granularity):\n\n- `ACL.all()`\n corresponds to access for all users.\n\n- `ACL.all_authenticated()` corresponds\n to access for all users that are signed into a Google account.\n\n- `ACL.domain()` corresponds to access on a\n per Google Apps domain (ie, `example.com`).\n\n- `ACL.group()` corresponds to access on a\n per group basis (either by ID or e-mail address).\n\n- `ACL.user()` corresponds to access on a\n per user basis (either by ID or e-mail address).\n\nAnd you are able to `grant` and `revoke` the following roles:\n\n- **Reading** :\n `_ACLEntity.grant_read()` and `_ACLEntity.revoke_read()`\n\n- **Writing** :\n `_ACLEntity.grant_write()` and `_ACLEntity.revoke_write()`\n\n- **Owning** :\n `_ACLEntity.grant_owner()` and `_ACLEntity.revoke_owner()`\n\nYou can use any of these like any other factory method (these happen to\nbe `_ACLEntity` factories): \n\n acl.user(\"me@example.org\").grant_read()\n acl.all_authenticated().grant_write()\n\nAfter that, you can save any changes you make with the\n[`google.cloud.storage.acl.ACL.save()`](/python/docs/reference/storage/latest/storage/acl#google.cloud.storage.acl.ACL.save) method: \n\n acl.save()\n\nYou can alternatively save any existing [`google.cloud.storage.acl.ACL`](/python/docs/reference/storage/latest/storage/acl#google.cloud.storage.acl.ACL)\nobject (whether it was created by a factory method or not) from a\n[`google.cloud.storage.bucket.Bucket`](/python/docs/reference/storage/latest/storage/bucket#google.cloud.storage.bucket.Bucket): \n\n bucket.acl.save(acl=acl)\n\nTo get the list of `entity` and `role` for each unique pair, the\n`ACL` class is iterable: \n\n print(list(acl))\n # [{'role': 'OWNER', 'entity': 'allUsers'}, ...]\n\nThis list of tuples can be used as the `entity` and `role` fields\nwhen sending metadata for ACLs to the API.\n\nIAM\n---\n\nIdentity and Access Management (IAM) controls permissioning throughout Google Cloud and allows you\nto grant permissions at the bucket and project levels. You should use IAM for any permissions that\napply to multiple objects in a bucket to reduce the risks of unintended exposure. To use IAM\nexclusively, enable uniform bucket-level access to disallow ACLs for all Cloud Storage resources.\nSee also:\n[Additional access control options](https://cloud.google.com/storage/docs/access-control#additional_access_control_options)\n\n### Constants used across IAM roles:\n\n- `STORAGE_OBJECT_CREATOR_ROLE = \"roles/storage.objectCreator\"`\n corresponds to role implying rights to create objects, but not delete or overwrite them.\n\n- `STORAGE_OBJECT_VIEWER_ROLE = \"roles/storage.objectViewer\"`\n corresponds to role implying rights to view object properties, excluding ACLs.\n\n- `STORAGE_OBJECT_ADMIN_ROLE = \"roles/storage.objectAdmin\"`\n corresponds to role implying full control of objects.\n\n- `STORAGE_ADMIN_ROLE = \"roles/storage.admin\"`\n corresponds to role implying full control of objects and buckets.\n\n- `STORAGE_VIEWER_ROLE = \"Viewer\"`\n corresponds to role that can list buckets.\n\n- `STORAGE_EDITOR_ROLE = \"Editor\"`\n corresponds to role that can create, list, and delete buckets.\n\n- `STORAGE_OWNER_ROLE = \"Owners\"`\n corresponds to role that can Can create, list, and delete buckets;\n and list tag bindings; and control HMAC keys in the project.\n\n### Constants used across IAM permissions:\n\n- `STORAGE_BUCKETS_CREATE = \"storage.buckets.create\"`\n corresponds to permission that can create buckets.\n\n- `STORAGE_BUCKETS_DELETE = \"storage.buckets.delete\"`\n corresponds to permission that can delete buckets.\n\n- `STORAGE_BUCKETS_GET = \"storage.buckets.get\"`\n corresponds to permission that can read bucket metadata, excluding ACLs.\n\n- `STORAGE_BUCKETS_LIST = \"storage.buckets.list\"`\n corresponds to permission that can list buckets.\n\n- `STORAGE_BUCKETS_GET_IAM_POLICY = \"storage.buckets.getIamPolicy\"`\n corresponds to permission that can read bucket ACLs.\n\n- `STORAGE_BUCKETS_SET_IAM_POLICY = \"storage.buckets.setIamPolicy\"`\n corresponds to permission that can update bucket ACLs.\n\n- `STORAGE_BUCKETS_UPDATE = \"storage.buckets.update\"`\n corresponds to permission that can update buckets, excluding ACLS.\n\n- `STORAGE_OBJECTS_CREATE = \"storage.objects.create\"`\n corresponds to permission that can add new objects to a bucket.\n\n- `STORAGE_OBJECTS_DELETE = \"storage.objects.delete\"`\n corresponds to permission that can delete objects.\n\n- `STORAGE_OBJECTS_GET = \"storage.objects.get\"`\n corresponds to permission that can read object data / metadata, excluding ACLs.\n\n- `STORAGE_OBJECTS_LIST = \"storage.objects.list\"`\n corresponds to permission that can list objects in a bucket.\n\n- `STORAGE_OBJECTS_GET_IAM_POLICY = \"storage.objects.getIamPolicy\"`\n corresponds to permission that can read object ACLs.\n\n- `STORAGE_OBJECTS_SET_IAM_POLICY = \"storage.objects.setIamPolicy\"`\n corresponds to permission that can update object ACLs.\n\n- `STORAGE_OBJECTS_UPDATE = \"storage.objects.update\"`\n corresponds to permission that can update object metadata, excluding ACLs."]]