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

The following naming rules apply to buckets.

• Bucket names are globally unique. Therefore, when you create a bucket, you must always enter a unique name.
  If Buckets names were only Account unique, then the Account name is required to make the URL or API call to the bucket unique. This means that the Account name could be publicly visible, depending on how the URL/API is used. To protect users from the inadvertent release of their Account name, Backblaze uses the unique bucket name instead. 
• Bucket names can consist of upper-case letters, lower-case letters, numbers, and "-".
  Multi-byte characters are not supported, and no other characters are allowed. The underscore character (_) is not valid in DNS tables. Allowing the underscore would limit the ability to cache files and would also limit the ability to create vanity URLs (a proposed future capability).
• Even though your bucket can include upper-case letters, bucket names are not case sensitive.
• A bucket name must be at least six characters long and can be at most 63 characters long.
• Bucket names that start with "b2-" are reserved for Backblaze's use and cannot be used.
• You cannot rename a bucket.

The following examples are allowed bucket names:

• myBucket
• backblaze-images
• bucket-74358734

 For file naming rules, click here.

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.