Create and manage access control lists (ACLs) (original) (raw)

Skip to main content

• Technology areas

  • Overview
  • Guides
  • Reference
  • Samples
  • Resources

• Cross-product tools

• Console

• Discover

• Product overview

• Storage Intelligence overview

• Get started

• Terraform support for Cloud Storage

• Configure and manage Storage Intelligence

• Create buckets

• Create a bucket

• Domain-named bucket verification

• Access and manage buckets

• List buckets

• Change the default storage class of a bucket

• Move and rename buckets

• Delete buckets

• Upload and download objects

• About objects

• Overview of uploads and downloads

• Access and manage objects

• List objects

• Copy, rename, and move objects

• Change an object's storage class

• Tools to access and manage objects using a directory structure

• Object transcoding

• Delete objects

• Get insights on your stored data

• Analyze stored data with Gemini Cloud Assist

• Cache objects

• About caching

• Control data lifecycles

• Options for controlling data lifecycles

• Make requests

• Consistency in Cloud Storage operations

• Batched requests

• Use long-running operations

• Paginate results

• URI wildcards

• Secure data

• Access control

  • Overview
  • Bucket IP filtering
    * Overview
    * Create a bucket with IP filtering rules
    * Create or update IP filtering rules on an existing bucket
    * Get IP bucket filtering rules
    * List bucket IP filtering rules
    * Delete bucket IP filtering rules
    * Disable bucket IP filtering
    * Bypass bucket IP filtering rules
  • Sharing and collaboration scenarios
  • Access control best practices

• Monitor data and usage

• Use Cloud Audit Logs with Cloud Storage

• Usage logs and storage logs

• Use Cloud Audit Logs with storage batch operations

• Use Cloud Logs with storage batch operations

• Use Cloud Audit Logs with Storage Insights

• Use gRPC client-side metrics

• Use client-side traces

• Protection, backup, and recovery

• Overview

• Soft delete

  • Overview
  • Set and manage soft delete policies
  • Use soft-deleted objects
  • Use soft-deleted buckets
  • Set a default soft delete retention duration
  • Use soft delete recommendations
  • Disable soft delete

• Mount buckets with Cloud Storage FUSE

• Overview

• Quickstart

• Install Cloud Storage FUSE

• Mount buckets

• Performance

  • Performance tuning best practices
  • Profile-based configurations for AI/ML workloads
  • Automated configuration values for high-performance machine types
  • Use pre-configured GKE YAML files to optimize Cloud Storage FUSE performance

• Work across products, Clouds, and platforms

• Best practices for media workloads

• Interoperability

• Use Cloud Storage with Big Data

• Integration with Google Cloud Platform services and tools

• Troubleshoot

• Troubleshooting common issues

• Troubleshooting Storage Insights issues

• Troubleshooting Cloud Storage FUSE issues

Create and manage access control lists (ACLs)

Overview

This page describes how to control access to buckets and objects using Access Control Lists (ACLs). ACLs are a mechanism you can use to define who has access to your buckets and objects, as well as what level of access they have.

See the ACL overview to learn more about whether you should use ACLs for controlling access to your resources.

Required roles

To get the permissions that you need to create and manage ACLs, ask your administrator to grant you the Storage Admin (roles/storage.admin) IAM role on the bucket that contains the objects for which you want to create and manage ACLs.

This predefined role contains the permissions required to create and manage ACLs. To see the exact permissions that are required, expand theRequired permissions section:

Required permissions

• storage.buckets.get
• storage.buckets.list
  • This permission is only required for using the Google Cloud console to perform the tasks on this page.
• storage.buckets.setIamPolicy
• storage.buckets.update
• storage.objects.get
• storage.objects.getIamPolicy
• storage.objects.setIamPolicy
• storage.objects.update

You can also get these permissions with custom roles.

For information about granting roles on buckets, seeSet and manage IAM policies on buckets.

Set or modify ACLs

Console

1. Go to the Cloud Storage browser in the Google Cloud console.
   Go to the Cloud Storage browser
2. From the list of buckets, click the name of the bucket that contains the object whose ACL you want to modify.
3. Click the name of the object for which you want to set or modify ACLs.
4. Click Edit access.
   A permission dialog with the object's current ACL opens.
5. Click + Add entry.
6. Choose the type of Entity to give permission to.
   Entity specifies the type of thing that's getting the permission (for example a user or a group). Refer to Access Control Scopesfor a list of supported values for Entity.
7. Enter a value in Name.
   Name identifies a specific user, group, or other entity type. Refer to Access Control Scopes for a list of supported values forName.
   Together, Entity and Name define who the permission applies to.
8. Choose a value in Access.
   Access defines the permission that you want to set on the object. Refer to Access Control Permissions for a list of supported values for Access.
9. Click Save.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

Command line

To add, modify, or remove an individual grant on an object, use theobjects update command with the relevant flag:

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME FLAG

Where:

• BUCKET_NAME is the name of the bucket that contains the object that the modification applies to. For example,example-travel-maps.
• OBJECT_NAME is the name of the object that the modification applies to. For example, paris.jpg.
• FLAG is one of the following:
  • --add-acl-grant, along with the grant you want to add or modify. For example, --add-acl-grant=entity=user-jeffersonloveshiking@gmail.com,role=READER.
  • --remove-acl-grant, along with the entity whose access you want to remove. For example, --remove-acl-grant=user-jeffersonloveshiking@gmail.com.

To replace all ACLs for an object:

1. Define the ACLs in a JSON- or YAML-formatted file.
   For example, the following ACLs grant the OWNER permission for the object paris.jpg to the owners of project 867489160491 and the userjeffersonloveshiking@gmail.com, as well as the READER permission for paris.jpg to the members of the gs-announce group:
   [
   {
   "entity": "project-owners-867489160491",
   "role": "OWNER",
   "projectTeam": {
   "projectNumber": "867489160491",
   "team": "owners"
   },
   },
   {
   "entity": "user-jeffersonloveshiking@gmail.com",
   "email": "jeffersonloveshiking@gmail.com",
   "role": "OWNER"
   },
   {
   "entity": "group-gs-announce@googlegroups.com",
   "email": "gs-announce@googlegroups.com",
   "role": "READER"
   }
   ]
2. Use the objects update command with the --acl-file flag:
   gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --acl-file=FILE_LOCATION
   Where:
   • BUCKET_NAME is the name of the bucket that contains the object that the ACLs apply to. For example,example-travel-maps.
   • OBJECT_NAME is the name of the object that the ACLs apply to. For example, paris.jpg.
   • FILE_LOCATION is the local path to the file that contains the ACLs you've defined. For example,Desktop/acls.json.

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample adds an ACL to an object:

The following sample removes an ACL from an object:

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample adds an ACL to an object:

The following sample removes an ACL from an object:

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample adds an ACL to an object:

The following sample removes an ACL from an object:

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample adds an ACL to an object:

The following sample removes an ACL from an object:

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample adds an ACL to an object:

The following sample removes an ACL from an object:

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample adds an ACL to an object:

The following sample removes an ACL from an object:

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample adds an ACL to an object:

The following sample removes an ACL from an object:

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample adds an ACL to an object:

The following sample removes an ACL from an object:

REST APIs

JSON API

When creating an object, you can specify the acl[] property in the request body or the predefinedAcl query parameter in an insertrequest. For an existing object, specify the acl[] property or thepredefinedAcl query parameter in a patch or update request.

For the definition of the object ACL property, see theObjectAccessControls resource.

1. Define the ACLs in a JSON file.
   For example, if the ACL grants the owners of project 867489160491and the user jeffersonloveshiking@gmail.com OWNER permission, along with granting the members of the gs-announce group READER permission, then you could have a file named acls.json with the following content:
   {
   "acl": [
   {
   "entity": "project-owners-867489160491",
   "role": "OWNER",
   "projectTeam": {
   "projectNumber": "867489160491",
   "team": "owners"
   }
   },
   {
   "entity": "user-jeffersonloveshiking@gmail.com",
   "role": "OWNER",
   "email": "jeffersonloveshiking@gmail.com"
   },
   {
   "entity": "group-gs-announce@googlegroups.com",
   "role": "READER",
   "email": "gs-announce@googlegroups.com"
   }
   ]
   }
2. Send a patch request with the JSON file, and specify the object to set the ACLs on.

For example, the following curl command applies a JSON payload from the document acls.json to an object named paris.jpg in the bucketexample-travel-maps:

curl -X PATCH --data @acls.json -H "Content-Type: application/json"
-H "Authorization: Bearer $(gcloud auth print-access-token)"
https://storage.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg

XML API

In the XML API, you work with ACLs in XML format. You must attach an XML document to the body of requests to change bucket and object ACLs. An XML document is returned when you get bucket and object ACLs. The XML document contains the individual bucket or object ACL entries.

• After creating a bucket with a PUT Bucket request, use a second PUT Bucket request with the ?acl parameter to change the bucket ACL.
• After uploading an object with a PUT Object request, change the ACL with another PUT request using the ?acl parameter or the x-googl-acl request header.

For example, the following curl command applies an XML payload from the document acls.xml to an object named paris.jpg in the bucketexample-travel-maps:

curl -X PUT --data-binary @acls.xml
-H "Authorization: Bearer $(gcloud auth print-access-token)"
https://storage.googleapis.com/example-travel-maps/paris.jpg?acl

Use the following ACL syntax for the XML document:

When working with ACLs using the XML API:

• You can only use the XML format described above.
• You cannot set duplicate scopes.
  You can have many entries in your ACL XML, but you cannot have entries with duplicate scopes. For example, you cannot have two entries with the same scope element of jane@example.com.

The following example shows different bucket ACL entries:

Set the Name element in ACL XML

When you retrieve an ACL from a bucket or object, you might notice an additional <Name> element appended to some of your entries. For example, you might see an entry that looks like the following:

These optional <Name> elements are populated in two circumstances:

1. When the bucket or object's ACLs include <Name> as an element.
   When you set ACLs, you can choose to include the <Name> element with your ACL entries. You can provide any value in the <Name> element, and Cloud Storage remembers these values until the ACL is removed or replaced. This approach can be useful if you are using identifiers that aren't easily identifiable.
2. When a UserByEmail or GroupByEmail scope contains a public Google profile.
   If you use either of these scopes but do not provide a <Name>element, Cloud Storage checks if the user or Google Group associated with the email address has a public Google profile with a public name. If so, Cloud Storage automatically populates the <Name> element with the public name.

Apply a predefined ACL

Rather than specifying the entire ACL one entry at a time as shown above, you can use a predefined ACL, which will automatically apply a number of entries customized to a specific scenario. You can apply a predefined ACL to either a bucket or an object by using the Google Cloud CLI, the JSON API, or the XML API.

On new objects

To apply a predefined ACL to an object during object upload:

Console

You cannot apply a predefined ACL using the Google Cloud console. Usegcloud storage instead.

Command line

Use the gcloud storage cp command with the --predefined-aclflag:

gcloud storage cp OBJECT gs://BUCKET_NAME --predefined-acl=PREDEFINED_ACL

For example, to apply the predefined ACL bucketOwnerRead while uploading an object paris.jpg to a bucket example-travel-maps:

gcloud storage cp paris.jpg gs://example-travel-maps --predefined-acl=bucketOwnerRead

REST APIs

JSON API

Use the predefinedAcl query string parameter in an insert request to apply the prefined ACL.

For example, to apply the predefined ACL bucketOwnerRead while uploading an object paris.jpg to a bucket example-travel-maps:

curl -X POST --data-binary @paris.jpg -H "Content-Type: image/jpeg"
-H "Authorization: Bearer $(gcloud auth print-access-token)"
"https://storage.googleapis.com/upload/storage/v1/b/example-travel-maps/o?name=paris.jpg&predefinedAcl=bucketOwnerRead"

XML API

Use the x-goog-acl header in a Put Object request to apply the predefined ACL.

For example, to apply the predefined ACL bucket-owner-read while uploading an object paris.jpg to a bucket example-travel-maps:

curl -X PUT --upload-file paris.jpg -H "x-goog-acl: bucket-owner-read"
-H "Authorization: Bearer $(gcloud auth print-access-token)"
https://storage.googleapis.com/example-travel-maps/paris.jpg

On existing buckets or objects

You can also apply a predefined ACL to an existing bucket or object, which is useful if you want to change from one predefined ACL to another, or you want to update custom ACLs to a predefined ACL.

Console

You cannot apply a predefined ACL using the Google Cloud console. Usegcloud storage instead.

Command line

Use the objects update command with the --predefined-acl flag:

gcloud storage objects update gs://BUCKET_NAME/OBJECT_NAME --predefined-acl=PREDEFINED_ACL_NAME

For example, to apply the predefined ACL private to the objectparis.jpg in the bucket example-travel-maps:

gcloud storage objects update gs://example-travel-maps/paris.jpg --predefined-acl=private

REST APIs

JSON API

Use the predefinedAcl query string parameter, and specify an empty aclproperty in a patch request to apply the prefined ACL.

For example, to apply the predefined ACL private to the objectparis.jpg in the bucket example-travel-maps:

curl -X PATCH --data '{"acl": []}' -H "Content-Type: application/json"
-H "Authorization: Bearer $(gcloud auth print-access-token)"
https://storage.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg?predefinedAcl=private

XML API

Use the x-goog-acl header with the acl query string parameter in aPut Object request, but don't include an XML document in your request.

For example, to apply the predefined ACL private to the objectparis.jpg in the bucket example-travel-maps:

curl -X PUT -H "Content-Length: 0"
-H "Authorization: Bearer $(gcloud auth print-access-token)"
-H "x-goog-acl: private"
https://storage.googleapis.com/example-travel-maps/paris.jpg?acl

Set default object ACLs

To avoid setting ACLs every time you create a new object, you can set a default object ACL on a bucket. After you do this, every new object that is added to that bucket that does not explicitly have an ACL applied to it will have the default applied to it. For example, you might want to specify that only a certain group of users have access to most objects in a particular bucket. You can change the default object ACL, and then add objects to the bucket. These added objects have the default object ACL you specified automatically applied to them; however, you can give specific objects different ACLs, in which case those objects do not have the default ACL applied to them.

To view and change the default object ACL for a bucket:

Console

You cannot set default object ACLs using the Google Cloud console. Usegcloud storage instead.

Command line

1. Use the buckets describe command with the --format flag to retrieve the default object ACL for the bucket:
   gcloud storage buckets describe gs://BUCKET_NAME --format="default(default_acl)"
   Where BUCKET_NAME is the name of the bucket whose default object ACL you want to view. For example, my-bucket.
2. Use the buckets update command with the desired flag to modify the default object ACL for the bucket:
   gcloud storage buckets update gs://BUCKET_NAME FLAG
   Where:
   • BUCKET_NAME is the name of the bucket whose default object ACL you want to modify. For example,my-bucket.
   • FLAG is one of the following:
     * --add-default-object-acl-grant and a grant that you want to add to the overall default object ACL for the bucket.
     * --default-object-acl-file and the path to a local file that defines a new default object ACL for the bucket.
     * --predefined-default-object-acl and the name of a predefined object ACL that you want to replace the existing default object ACL for the bucket with.
     * --remove-default-object-acl-grant and an entity that you want to remove from the overall default object ACL for the bucket.

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample adds a default object ACL to a bucket:

The following sample deletes a default object ACL from a bucket:

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample prints the default object ACL for a bucket:

The following sample adds a default object ACL to a bucket:

The following sample deletes a default object ACL from a bucket:

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample adds a default object ACL to a bucket:

The following sample deletes a default object ACL from a bucket:

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample adds a default object ACL to a bucket:

The following sample deletes a default object ACL from a bucket:

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample adds a default object ACL to a bucket:

The following sample deletes a default object ACL from a bucket:

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample adds a default object ACL to a bucket:

The following sample deletes a default object ACL from a bucket:

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample adds a default object ACL to a bucket:

The following sample deletes a default object ACL from a bucket:

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample adds a default object ACL to a bucket:

The following sample deletes a default object ACL from a bucket:

REST APIs

JSON API

1. Retrieve the default object ACL with a GET request. For example:
   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?projection=full
2. Use a patch request to replace the default object ACL. For example, the following request replaces the default object ACL with the ACL specified in defacls.json for a bucketexample-travel-maps:
   curl -X PATCH --data @defacls.json -H "Content-Type: application/json" -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   https://storage.googleapis.com/storage/v1/b/example-travel-maps
   An example of defacls.json:
   {
   "defaultObjectAcl": [
   {
   "email": "jeffersonloveshiking@gmail.com",
   "entity": "user-jeffersonloveshiking@gmail.com",
   "role": "READER"
   }
   ]
   }

XML API

1. Retrieve the default object ACL with a GET request scoped to your bucket and the ?defaultObjectAcl parameter. For example:
   curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   https://storage.googleapis.com/BUCKET_NAME?defaultObjectAcl
2. Use a PUT request scoped to your bucket with the?defaultObjectAcl parameter to replace the default object ACL with the ACL specified in acls.xml. For example:
   curl -X PUT --data-binary @acls.xml -H "Authorization: Bearer $(gcloud auth print-access-token)" \
   http://storage.googleapis.com/BUCKET_NAME?defaultObjectAcl
   An example of acls.xml: `FULL_CONTROL` jeffersonloveshiking@gmail.com

The syntax of ACLs is discussed in Setting ACLs. You can also specify a predefined ACL as the default object ACL.

To set the default object ACL for a bucket to a predefined ACL:

Console

You cannot set default object ACLs using the Google Cloud console. Usegcloud storage instead.

Command line

Use the buckets update command with the--predefined-default-object-acl flag:

gcloud storage buckets update gs://BUCKET_NAME --predefined-default-object-acl=PREDEFINED_ACL

Where:

• BUCKET_NAME is the name of the bucket whose default object ACL you want to modify. For example,my-bucket.
• PREDEFINED_ACL is the name of a valid predefined ACL. For example, projectPrivate.

REST APIs

JSON API

Use a PUT request and the predefinedAcl parameter.

For example:

curl -X PUT -H "Content-Length: 0" -H "Authorization: Bearer $(gcloud auth print-access-token)"
https://storage.googleapis.com/storage/v1/b/BUCKET_NAME?predefinedAcl=private

XML API

Use a PUT request scoped to your bucket with the ?defaultObjectAclparameter and the x-goog-acl header.

For example:

curl -X PUT -H "x-goog-acl: project-private" -H "Content-Length: 0" -H "Authorization: Bearer $(gcloud auth print-access-token)"
http://storage.googleapis.com/BUCKET_NAME?defaultObjectAcl

Default object ACLs for newly created buckets:

The following examples show the default object ACLs that automatically apply to newly created buckets when you don't specify your own default object ACLs as part of the request. To see if your bucket's default object ACLs have been changed, compare your bucket's current default object ACLs to the examples below.

Console

You cannot work with default object ACLs using the Google Cloud console. Use gcloud storage instead.

Command line

In the example below, the project ID is "123412341234"; your project ID will be different.

defaultObjectAcl: – entity: project-owners-123412341234 etag: CAE= kind: storage#objectAccessControl projectTeam: projectNumber: '123412341234' team: owners role: OWNER – entity: project-editors-123412341234 etag: CAE= kind: storage#objectAccessControl projectTeam: projectNumber: '123412341234' team: editors role: OWNER – entity: project-viewers-123412341234 etag: CAE= kind: storage#objectAccessControl projectTeam: projectNumber: '123412341234' team: viewers role: READER

REST APIs

JSON API

In the example below, the project ID is "123412341234"; your project ID will be different.

"defaultObjectAcl": [ { "kind": "storage#objectAccessControl", "entity": "project-owners-123412341234", "role": "OWNER", "projectTeam": { "projectNumber": "123412341234", "team": "owners" } }, { "kind": "storage#objectAccessControl", "entity": "project-editors-123412341234", "role": "OWNER", "projectTeam": { "projectNumber": "123412341234", "team": "editors" } }, { "kind": "storage#objectAccessControl", "entity": "project-viewers-123412341234", "role": "READER", "projectTeam": { "projectNumber": "123412341234", "team": "viewers" } } ]

XML API

In the example below, the project role IDs start with "00b4903a97..."; your project IDs will be different.

Note that the default object ACL for a newly created bucket is equivalent to the predefined projectPrivate ACL.

Retrieving ACLs

To get the ACL of an existing resource:

Console

1. Go to the Cloud Storage browser in the Google Cloud console.
   Go to the Cloud Storage browser
2. Navigate to the object whose ACL you want to view.
3. Choose Edit access from the drop-down menu for the object.
   You should see a permission dialog with the object's permissions.

To learn how to get detailed error information about failed Cloud Storage operations in the Google Cloud console, seeTroubleshooting.

Command line

1. Use the objects describe command with the --format flag to retrieve an object's ACL:
   gcloud storage objects describe gs://BUCKET_NAME/OBJECT_NAME --format="default(acl)"
   Where:
   • BUCKET_NAME is the name of the bucket containing the object whose ACL you want to view. For example,my-bucket.
   • OBJECT_NAME is the name of the object whose ACL you want to view. For example, paris.jpg.

Client libraries

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample gets an object ACL:

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample gets an object ACL:

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample gets an object ACL:

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample gets an object ACL:

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample gets an object ACL:

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample gets an object ACL:

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample gets an object ACL:

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

The following sample gets an object ACL:

REST APIs

JSON API

1. Make sure that you have OWNER permission on the object.
2. Retrieve the object's ACL with a GET request.
   The object ACL is returned in JSON format, attached to the body of the response.

For example, to return the ACL for the object paris.jpg in the bucketexample-travel-maps:

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)"
https://storage.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg?projection=full

You should see a response that looks like:

{ "kind": "storage#object", "id": "example-travel-maps/paris.jpg/1412805837131000", "selfLink": "https://www.googleapis.com/storage/v1/b/example-travel-maps/o/paris.jpg", "name": "paris.jpg", "bucket": "example-travel-maps", ... "acl": [ { ... "entity": "project-owners-867489160491", "role": "OWNER", "projectTeam": { "projectNumber": "867489160491", "team": "owners" }, ... }, { ... "entity": "user-jeffersonloveshiking@gmail.com", "role": "OWNER", "email": "jeffersonloveshiking@gmail.com", ... }, { ... "entity": "group-gs-announce@googlegroups.com", "role": "READER", "email": "gs-announce@googlegroups.com", ... } ], "owner": { "entity": "user-jeffersonloveshiking@gmail.com" }, ... }

You can also use the objectAccessControls resource GET method to return individual entries in an object's ACL.

XML API

1. Make sure that you have FULL_CONTROL permission on the bucket or object.
2. Retrieve the bucket or object's ACL by using the acl query string parameter in a GET Object request.

The ACLs are described in XML, attached to the body of the response.

For example, to return the ACL for the object paris.jpg in the bucketexample-travel-maps:

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)"
https://storage.googleapis.com/example-travel-maps/paris.jpg?acl

You should see a response that looks like:

You can also use the JSON GET method of the ObjectAccessControlsresource to return a specific ACL entry.

What's next

• Learn more about ACLs.
• Learn how to simplify your access control using uniform bucket-level access.
• Learn about best practices when using ACLs.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-09 UTC.