Source Code Bundles
S3 Compatible API
The Backblaze S3 Compatible API adds a new API to allow existing S3 integrations and SDKs to easily integrate with Backblaze B2 Cloud Storage. This documentation will serve as a resource for developers and end-users to distinguish the differences between the S3 Compatible API for Backblaze B2 and the Amazon S3 API. If you’re looking to get started with the S3 Compatible API, please refer to our Getting Started guide here.
The Backblaze S3 Compatible API only supports v4 signatures for authentication and does not support v2 signatures at this time. To learn more about S3 authentication, see this article.
The Backblaze S3 Compatible API returns calls in the same way the AWS S3 API does. Note that this may vary slightly from AWS S3 API documentation - this difference is expected based on the AWS S3 API. Here are the calls that are supported:
The Backblaze S3 Compatible API features limited support for ACLs (Access Control Lists). Get Object ACL and Get Bucket ACL calls will work as expected. However, object-level ACLs are not supported. For example, a Get Object ACL call returns the ACL for the Bucket the object is contained in.
If a Bucket is Private, the ACL returned for the Bucket and any files within the bucket will be “PRIVATE”. If a Bucket is Public, the ACL returned for the Bucket and any files within the bucket will be “PUBLIC_READ”.
The S3 Compatible API supports the Put Bucket ACL call to change between the Get Object ACL and Get Bucket ACL calls only. Attempting to put a different value will return an error.
Access Key ID and Secret Access Key
For the purposes of terminology, the Application Key and Application Key ID are the equivalent of the Secret Access Key and Access Key ID respectively. For more information about App Keys, please see our documentation here.
Application Key Restrictions
The automatically created Master Application Key is not supported in the Backblaze S3 Compatible API - only Application Keys that are manually created in the Backblaze Web UI or via the Backblaze B2 Native API can be used to authenticate the Backblaze S3 Compatible API.
If an Application Key is restricted to a bucket, the listAllBucketNames permission is required for compatibility
with SDKs and integrations. The listAllBucketNames permission can be enabled upon creation in the web UI or using
The Delete Object call may require that the App Key have both the writeFiles and deleteFiles capabilities. The writeFiles permission is necessary when deleting by name and the deleteFiles permission is required when deleting a specific version. As a general rule, both the writeFiles and deleteFiles permissions should be associated with the key used for deleting files in the S3 Compatible API.
The Backblaze S3 Compatible API does not support unauthenticated ListObject calls on Public Buckets.
Buckets in Backblaze B2 Cloud Storage are versioned by default. Because Buckets are versioned, when a file is deleted by referencing the name only the most recent version of that file will be deleted and older versions of the file will continue to exist in the Bucket. Older versions of files can be deleted automatically by using the Backblaze Lifecycle Rules. Lifecycle Rules are currently only available through the Backblaze Web UI and the Backblaze B2 Native API.
The format for endpoints for the Backblaze S3 Compatible API:
The Backblaze S3 Compatible API endpoints only accept connections over HTTPS. Non-secure connections will be rejected. The AWS SDKs and most integrations only require an Endpoint URL like the above (without the bucket name included).
If making the HTTP calls directly, the Backblaze S3 Compatible API supports specifying the bucket name in the hostname of the URL or in the path section of the URL. Both URLs below are valid examples of an endpoint calling a bucket:
The Backblaze S3 Compatible API supports pre-signed URLs for downloading and uploading. The pre-signed URLs can be generated in a number of ways including the AWS CLI, AWS Tools for PowerShell, and AWS SDKs.
The Backblaze S3 Compatible API can be used with existing AWS SDKs. Guides on how to configure the AWS SDKs can be found in the knowledge base:
The Backblaze S3 Compatible API does not currently support the following features:
When uploading multiple versions of the same file within the same second, the possibility exists that the processing of these versions may not be in order. Backblaze recommends delaying uploads of multiple versions of the same file by at least one second to avoid this situation.
Similarly, when hiding a file within the same second as uploading that file, it is possible that the file may not actually be hidden. To avoid such a situation, please delay such calls on the same file by at least one second.
Several features are on our roadmap to be included in a future release for the Backblaze S3 Compatible API. Once new features are supported more information will be added to this page.
Have a request or idea for the Backblaze S3 Compatible API? Please feel free to contact us at [email protected].