Buckets

The storage for your account is grouped into buckets. Each bucket is a container that holds files. You can think of buckets as the top-level folders in your Backblaze B2 Cloud Storage account. There is no limit to the number of files in a bucket, but there is a limit of 100 buckets per account. Contact the Support team if you need more than 100 buckets.

You can host web content using Backblaze B2. However, you cannot directly map a domain name to a Backblaze B2 bucket. You can use Cloudflare as a potential workaround. You can find a guide to get started with Cloudflare here.

The following API calls are related to buckets:

• b2_create_bucket - This operation creates a new bucket in your account.
• b2_delete_bucket - This operation deletes one bucket.
• b2_list_buckets - This operation lists all of the buckets in your account.
• b2_update_bucket - This operation updates the settings for a bucket.

Bucket Names

Bucket names are globally unique across all Backblaze B2 accounts. When you create a bucket, you must enter a name that is not already in use.

B2 Native API Naming Rules

The following naming rules apply to all Backblaze B2 buckets:

• Bucket names must be at least 6 characters and no more than 63 characters long.
• Bucket names can consist of upper-case letters, lower-case letters, numbers, and hyphens (-).
• Bucket names are not case sensitive, even though they can include upper-case letters.
• Multi-byte characters are not supported. The underscore character (_) is not valid because it would limit DNS compatibility and the ability to create vanity URLs.
• Bucket names that start with b2- are reserved for Backblaze use.
• You cannot rename a bucket after it is created.

The following are valid bucket names:

• myBucket
• backblaze-images
• bucket-74358734

 For file naming rules, click here.

S3-Compatible API Naming Rules

If you access your buckets through the S3-Compatible API or connect third-party integrations—such as backup tools, media applications, or cloud sync services—your bucket names must also comply with AWS S3 general purpose bucket naming conventions.

Character and length requirements:

• Bucket names must be between 3 and 63 characters long.
• Bucket names can consist only of lowercase letters, numbers, periods (.), and hyphens (-).
• Bucket names must begin and end with a letter or number.
• Bucket names must not contain two adjacent periods (..).
• Bucket names must not be formatted as an IP address (for example, 192.168.5.4).

Reserved prefixes:

Bucket names must not start with the following prefixes:

• xn--
• sthree-
• amzn-s3-demo-

Reserved suffixes:

Bucket names must not end with the following suffixes:

• -s3alias (reserved for access point alias names)
• --ol-s3 (reserved for Object Lambda Access Point alias names)
• .mrap (reserved for Multi-Region Access Point names)
• --x-s3 (reserved for directory buckets)
• --table-s3 (reserved for S3 Tables buckets)

Transfer Acceleration:

Buckets used with Amazon S3 Transfer Acceleration cannot have periods (.) in their names.

Recommendation

For maximum compatibility with partner integrations and the S3-Compatible API, Backblaze recommends following these combined guidelines for all new buckets:

• Use only lowercase letters, numbers, and hyphens (-)
• Use at least 6 characters (required by B2) and no more than 63 characters
• Begin and end with a lowercase letter or number
• Bucket names cannot contain periods (.)
• Avoid the reserved prefixes and suffixes listed above

Access Controls

Authorization is always required for the following actions:

• Uploading files into a bucket
• Listing files in a bucket
• Deleting files

To download files, you have the option to require authorization, or you can make all of the files in a bucket visible to the public.

• Set the bucketType parameter to allPrivate to require an authorization token for every download.
• Set the bucketType parameter to allPublic to allow any user to download the files in the bucket.

If a bucket is set to allPublic, any user can download the files, but the downloads are still charged against your account. Each day, anything beyond the 1 GB of free downloads is charged to your account.

Bucket Information

You can add key/value pairs as custom information associated with the bucket. Each key is a UTF-8 string up to 50 bytes long, and they can contain letters, numbers, and the following list of special characters: "-", "_", ".", "`", "~", "!", "#", "$", "%", "^", "&", "*", "'", "|", "+". Each key is converted to lower case. Names that begin with "b2-" are reserved for internal use. There is an overall limit of 10,000 bytes for all of the values.

You can store bucket information when you create a bucket with the b2_create_bucket operation, and then update the information later with the b2_update_bucket operation. 

There is no limit on the size or content of the values, other than the overall size limit.

You can also set the cache-control policy for buckets. For example, if you want the client to cache files for five minutes, you add a name/value pair such as "Cache-Control" : "max-age=600"; from then on, when you download any files from this bucket, the response contains the corresponding header. By default, if you do not set a cache-control policy, all files that you download from buckets that you created before September 8, 2021 have a cache-control header value of "max-age=0, no-cache, no-store". All buckets that you created on or after September 8, 2021 include no cache-control header with file downloads by default.

Lifecycle Rules for Buckets

Each bucket has a set of lifecycle rules that instruct Backblaze B2 to hide or delete old versions of files.

Sharing Buckets

When you create a bucket, it is part of the account it is created under. If you want to share the bucket with other users, there are a few ways that you can do so.

1. Sharing Credentials
   The first, and most simple option, is to provide the sign in credentials (your username and password) to those you want to have access to the bucket. However, if you do not want other users to have access to your credentials, this is not ideal for you.
2. Create a Group
   If you do not want to share sign-in information, but you still want other users to be able to view and access the bucket as you would through your account, you can create a Group. Ensure that the group is set to "managed," invite the account with the bucket to the Group, and add all of the users that you want to be able to access the bucket as admins of that Group. For specific instructions for creating and administering Groups, see Create and Manage Groups.
3. Share Access Using Application Keys
   Another option, if you do not want the account where the bucket is housed to be viewable, and only a specific bucket, is to do so through application keys. You can create an application key with permission to access the bucket and share the key and key ID with the users you want to have access to that bucket. Then, the easiest way for them to access the bucket is to use those credentials with one of Backblaze supported integrations, although it is also possible to do so through the Command-Line Interface.
   For more about application keys, click here.
   For a full list of partner integrations, click here.

Folders

A bucket in the Backblaze B2 object storage system has a flat structure. This means that, unlike a traditional file system, a bucket does not contain a hierarchy of directories or folders. However, the concept or look and feel of a folder is supported in the form of a virtual folder. Under the hood, a virtual folder is just a prefix or string of characters (the folder’s name is the prefix string) that is added to the beginning of a filename. 

For example, the following files are grouped within a bucket using the music/ prefix:  

music/song1.mp3

music/song2.mp3

music/song3.mp3

Multiple prefixes can also provide the look and feel of a nested folder hierarchy:

music/2025/song1.mp3

music/2025/song2.mp3

music/2024/song1.mp3

music/2024/song2.mp3

Note the use of / to separate the prefixes (music/, 2025/, 2024/) from the filenames (song1.mp3, song2.mp3, song3.mp3). Backblaze recommends that you use / to separate the prefixes so tools can determine the implied folder structure. Additionally, / is commonly used as a delimiter when searching for files with the B2 Native API or S3-Compatible API.

For more information about file names, click here.

Working With Buckets

Many GUI tools that allow you to interact with a bucket, such as the Backblaze web console or third-party file management solutions, present objects with prefixes as files that are organized into folders for ease of use. However, when using the B2 Native API or the Command-Line Interface (CLI), you work directly with prefixes to organize and search your data.

You can create an empty virtual folder in a bucket using the Backblaze web console, third-party file management tools, or programmatically using the B2 Native API or S3-Compatible API.

For any B2 Native API or S3-Compatible API file-related operations that involve a folder, include the target folder name as a prefix in the appropriate parameter. Prefixes can be used to add files to a folder, as well as other common file operations such as copying, listing, and deleting. If the target virtual folder does not exist, a new virtual folder is created based on the prefix string that you include in the API call. For more information, refer to the documentation for the specific API operation.