Docs

Torch Object Storage

ACLs

Overview

An access control list (ACL) is a set of permissions that determine who can access specific resources in TOS.

Introduction

An ACL is a mechanism for managing read and write access based on user accounts, where the bucket or object owner has full control over the resource.

ACLs are less refined than bucket or Identity and Access Management (IAM) policies. Therefore, we recommend that you use the bucket or IAM policies for access control.

Grantee

ACLs categorize grantees into two types: specified users and predefined groups.

Specified users: IAM users. To grant different IAM users different permissions, use bucket policies.

Predefined groups:

Group
Description
AuthenticatedUsers
All users who are signed in or authenticated.
AllUsers
All users, regardless of whether they are authenticated or anonymous.

What permissions can I grant?

The following table lists the permissions supported by TOS in an ACL.

Permission	When granted on a bucket	When granted on an object
READ	Allows the grantee to obtain bucket metadata and list objects and multipart uploads within the bucket.	Allows the grantee to read the object data and its metadata.
READ_NON_LIST	Allows the grantee to obtain bucket metadata.	Allows the grantee to read the object data and its metadata.
READ_ACP	Allows the grantee to read the bucket ACL.	Allows the grantee to read the object ACL.
WRITE	Allows the grantee to create, overwrite, or delete any object in the bucket and to initialize, complete or abort multipart uploads.	Not applicable.
WRITE_ACP	Allows the grantee to modify or delete the bucket ACL.	Allows the grantee to modify the object ACL.
FULL_CONTROL	Grants the READ, WRITE, READ_ACP, and WRITE_ACP permissions for the bucket.	Grants the READ, READ_ACP, and WRITE_ACP permissions for the object.

warning

Buckets with public-read permissions are exposed on the public network. Anyone can read or write objects in these buckets, which incurs data transfer costs and may result in property loss or data leakage. Therefore, we recommend setting the access permission policy to private.

Setting ACL using request headers

When you send a request to TOS, you can set a predefined ACL using the x-tos-acl request header. The following table lists the set of predefined ACLs and their descriptions.

Predefined ACL	Description
private	The bucket or object owner has full control, and other users have no permissions. The default policy is private.
public-read	When granted on a bucket: All users have READ permission for the bucket. When granted on an object: All users have READ permission for the object.
public-read-write	When granted on a bucket: All users have READ and WRITE permissions for the bucket. When granted on an object: All users have READ permission for the object.
authenticated-read	When granted on a bucket: All authenticated users have READ permission for the bucket. When granted on an object: All authenticated users have READ permission for the object.
bucket-owner-read	Applies to objects. Both the object owner and the bucket owner have READ permission for the object.
bucket-owner-full-control	Applies to objects. Both the object owner and the bucket owner get full control over the object.
bucket-owner-entrusted	Applies to objects. Granting this permission to an object gives the bucket owner full control over the object, even if the object's owner is not the bucket's owner. Through a bucket policy, the bucket owner can grant or revoke access to the object for other accounts or users.
default	Applies to objects. The object inherits the permissions from its bucket. In other words, the object's ACL will mirror the bucket's.

You can grant the specified users the corresponding permissions via the following request headers.

Request header	Description
x-tos-grant-read	Grants READ permission.
x-tos-grant-read-acp	Grants READ_ACP permission.
x-tos-grant-read-non-list	x-tos-grant-read-non-list must be used with x-tos-grant-read-acp. It is meaningless when used alone. This header is used to revoke permission to list objects and multipart uploads within a bucket. When used with x-tos-grant-read-acp, it indicates that the grantee has the READ_NON_LIST permission.
x-tos-grant-write	Grants WRITE permission.
x-tos-grant-write-acp	Grants WRITE_ACP permission.
x-tos-grant-full-control	Grants FULL_CONTROL permission.

Managing object permissions using bucket ACLs

TOS allows you to set an object's ACL to Inherit bucket, meaning the ACL of the object will mirror the bucket's ACL. The following describes the permissions of an object that has inherited the ACL of its bucket, such as READ and WRITE.

Permission	Bucket ACL	Object permissions after inheritance
READ	Allows the grantee to obtain metadata for the bucket and its objects, download objects, and list objects and multipart uploads within the bucket.	Allows the grantee to read the object data and its metadata.
READ_NON_LIST	Allows the grantee to obtain bucket metadata and access objects within the bucket.	Allows the grantee to read the object data and its metadata.
WRITE	Allows the grantee to create, overwrite, or delete any object in the bucket and to initialize, complete, or abort multipart uploads.	There are no write APIs available for objects. Even after an object inherits the WRITE ACL from the bucket, the grantee has no effective permissions on the object. Only the bucket or object owner retains full control permissions.
READ_ACP	Allows the grantee to read the bucket ACL.	Allows the grantee to read the object ACL.
WRITE_ACP	Allows the grantee to modify or delete the bucket ACL.	Allows the grantee to modify the object ACL.
FULL_CONTROL	Grants the READ, WRITE, READ_ACP, and WRITE_ACP permissions for the bucket.	Grants the READ, READ_ACP, and WRITE_ACP permissions for the object.

Next steps

Configuring bucket ACLs

Configuring object ACLs

Last updated: 2026.06.17 18:21:51

Group	Description
AuthenticatedUsers	All users who are signed in or authenticated.
AllUsers	All users, regardless of whether they are authenticated or anonymous.